BuzzTrail

A comprehensive system for BuzzTrail that enhances the user experience with advanced features and integrations.

🚀 Current Focus: Slidev Control System - PRODUCTION READY ✅

$3

We have successfully deployed the Slidev Control MVP, a complete system for generating and controlling Slidev presentations in real-time. The system is production-ready and deployed on Railway.

Production URL: https://slide-system-production-5813.up.railway.app

$3

✅ API Layer (Motia.dev on Railway)
- POST /api/slidev/generate - Deck generation endpoint
- POST /api/slidev/control - Real-time control commands
- POST /demo-sessions - Session creation
- Production deployment with automatic CI/CD from main branch

✅ Database & Realtime (Supabase)
- conversation_sessions table - Session lifecycle tracking
- slidev_decks table - Generated deck metadata
- slide_control_commands table - Real-time command broadcasting
- Supabase Realtime enabled for instant command delivery

✅ Presentation Hosting (GitHub Pages)
- Static hosting for generated presentations
- CDN-powered global delivery
- Real-time control via Supabase subscription
- URL format: https://buzztrail.github.io/buzztrail-presentations/{deckId}/

✅ Testing Infrastructure
- Performance testing framework (scripts/performance-test.ts)
- Concurrent load testing (scripts/concurrent-test.ts)
- E2E testing with Playwright
- All performance targets exceeded

📊 Performance: Exceeding all targets
- Build time: ~15s (target: < 30s) ✅
- Total generation: ~60s (target: < 90s) ✅
- Control latency: ~200ms (target: < 500ms) ✅
- Success rate: 100% (target: > 95%) ✅
- Concurrent capacity: 15+ (target: 10+) ✅

📚 Complete Documentation:
- API Documentation - Full API reference
- Architecture Documentation - System design
- Railway Deployment Guide - Deployment instructions
- Monitoring Guide - Production monitoring
- Troubleshooting Guide - Common issues
- Production Checklist - Deployment readiness

$3

``bash
SESSION_ID=$(curl -s -X POST https://slide-system-production-5813.up.railway.app/demo-sessions \
-H "Content-Type: application/json" \
-d '{"session_type":"test","environment":"prod"}' | jq -r '.session_id')

curl -X POST https://slide-system-production-5813.up.railway.app/api/slidev/generate \
-H "Content-Type: application/json" \
-d "{\"sessionId\":\"$SESSION_ID\",\"templateId\":\"starter\",\"data\":{\"company\":\"Acme Corp\"}}"

curl -X POST https://slide-system-production-5813.up.railway.app/api/slidev/control \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"deckId":"DECK_ID","command":"next"}'
`

See API Documentation for complete details.

$3

- ✅ Nx Monorepo: Modern workspace structure with shared libraries
- ✅ Motia Integration: AI-powered backend workflows and automation
- ✅ Serverless Functions: Vercel deployment for API endpoints
- ✅ Type Safety: Full TypeScript implementation
- ✅ Shared Libraries: Reusable components and utilities across apps
- ✅ Modern Tooling: pnpm, Nx, Motia, and Vercel integration

$3

`
┌──────────────────┐
│ Pipecat Agent │
│ (Conversation) │
└────────┬─────────┘
│
▼
┌─────────────────────────────────────────┐
│ slide-system (Railway) │
│ - POST /api/slidev/generate │
│ - POST /api/slidev/control │
│ - POST /demo-sessions │
└────┬────────────────────┬───────────────┘
│ │
▼ ▼
┌────────────────┐ ┌──────────────────┐
│ Supabase │ │ GitHub Pages │
│ - Database │ │ (Presentations) │
│ - Realtime │ └────────┬─────────┘
└────┬───────────┘ │
│ │
└────────────────────────┼──────────┐
▼ │
┌──────────────────┐ │
│ Customer Browser │◄┘
│ (Presentation + │
│ Realtime sync) │
└──────────────────┘
`

$3

#### slide-system (Production on Railway)
Motia.dev API backend providing:
- Slidev deck generation with template processing
- Real-time presentation control via Supabase
- Demo session management
- URL: https://slide-system-production-5813.up.railway.app
- Docs: apps/slide-system/README.md

#### proxy-server (Vercel)
API proxy and webhook handling:
- Health check endpoint
- Conversation management
- Webhook processing

#### backup-workflows (Motia)
Backend workflow automation:
- Customer data backup workflows
- Multi-tenant data management
- Event-driven processing

#### demos
Customer-facing demo UI:
- Demo presentation interface
- User interaction layer

#### extension
Browser extension for enhanced functionality

---

🏗️ Project Structure

This is an Nx monorepo containing multiple applications and libraries:

`
├── apps/
│ ├── proxy-server/ # Vercel serverless functions
│ ├── extension/ # Browser extension
│ ├── chatbot/ # Chat interface
│ ├── backup-workflows/ # Motia backend workflows (CURRENT FOCUS)
│ ├── demos/ # Demo applications
│ └── [other-apps]/
├── libs/
│ ├── shared/ # Shared utilities and components
│ │ ├── utils/ # API clients, logging, utilities
│ │ ├── components/ # React components
│ │ ├── types/ # TypeScript type definitions
│ │ ├── config/ # Configuration utilities
│ │ ├── constants/ # Shared constants
│ │ ├── icons/ # Icon components
│ │ ├── styles/ # Styling utilities
│ │ ├── themes/ # Theme system
│ │ └── ui/ # UI components
│ └── [other-libs]/
├── documentation/ # Project documentation
└── tools/ # Development tools and scripts
`

🛠️ Development Setup

$3

- Node.js (v22 or higher)
- pnpm (v10.17.0 or higher)
- Nx CLI (optional, but recommended)

$3

`bash


Install dependencies

pnpm install

Verify Nx installation

pnpm nx --version
`

🚀 Deployment

$3

The proxy-server is deployed to Vercel as serverless functions:

Configuration:
- Root Directory: apps/proxy-server
- Build Command: npx nx build proxy-server
- Install Command: pnpm install
- Framework: Other (Custom Node.js)

Environment Variables:
- ENABLE_EXPERIMENTAL_COREPACK=1 (for pnpm support)
- TAVUS_API_KEY (for API integration)

Deployment URL: https://buzztrail-proxy.vercel.app

$3

`bash


Start proxy server locally

pnpm nx serve proxy-server

Start Motia backend workflows

pnpm nx serve backup-workflows

Start other applications

pnpm nx serve [app-name]
`

$3

`bash


Build all applications

pnpm nx build --prod

Build specific application

pnpm nx build proxy-server --prod
`

Type Checking

BuzzTrail enforces comprehensive type checking across TypeScript and Python codebases. Our three-layer type checking system (local pre-commit hooks, CI/CD pipeline, and production builds) protects all four production environments from type-related bugs.

$3

Type checking prevents runtime errors before they reach production. Our system deploys to:

- Railway (https://slide-system-production-5813.up.railway.app) - 24/7 API backend + Python bots
- Vercel (https://buzztrail-proxy.vercel.app) - Serverless functions with cold start sensitivity
- GitHub Pages (https://buzztrail.github.io/buzztrail-presentations/) - Public-facing presentations
- Supabase - Database/realtime with strict data integrity requirements

Type errors in any environment can cascade into complete system failures. Our comprehensive checks catch these errors before deployment.

$3

`bash


TypeScript - Check all projects

pnpm nx run-many -t typecheck --all

TypeScript - Check affected projects (what CI checks)

pnpm nx affected -t typecheck --base=main

TypeScript - Check specific project

pnpm nx typecheck slide-system

ESLint - Type-aware linting (all projects)

pnpm nx run-many -t lint --all

ESLint - Affected projects only

pnpm nx affected -t lint --base=main

Python - Check both bots

./scripts/python-typecheck.sh

Python - Check specific bot manually

cd apps/slide-system/bots/screenshare-bot
source .venv/bin/activate
mypy bot.py

Comprehensive check - All TypeScript, ESLint, and Python

./scripts/typecheck-all.sh
`

$3

Husky automatically runs type checks on every commit:

1. TypeScript type checking (affected files only)
2. ESLint type-aware linting (affected files only)
3. Python mypy validation (if .py files changed)

Typical run time: 10-30 seconds. This catches errors immediately before they enter version control.

Emergency bypass (use sparingly):
`bash
git commit --no-verify -m "fix: emergency production hotfix"
`

When to bypass:
- Production outage requiring immediate fix
- Committing non-code files only
- Pre-commit hook has a bug

When NOT to bypass:
- "I'll fix types later" - Fix them now
- "CI will catch it" - Waste of CI time
- "Just a small change" - Small bugs cause big outages

$3

Type checking runs on every push and pull request with three parallel jobs:

#### 1. TypeScript Type Checking
`bash
pnpm nx affected --target=typecheck --base=$BASE --parallel=3
`
- Validates all TypeScript compilation
- Checks affected projects only
- Fails build on any tsc errors
- Typical runtime: 2-5 minutes

#### 2. ESLint Type-Aware Linting
`bash
pnpm nx affected --target=lint --base=$BASE --parallel=3
`
- Runs ESLint with type-aware rules
- Catches async/await issues, promise handling, etc.
- Fails build on any lint violations
- Typical runtime: 2-5 minutes

#### 3. Python Type Checking
`bash
mypy bot.py --ignore-missing-imports
`
- Validates Python type hints in both bots
- Creates isolated venv per bot
- Fails build on any mypy errors
- Typical runtime: 1-3 minutes

All three jobs must pass before the build job runs. Pull requests with type errors cannot be merged.

See .github/workflows/ci.yml for implementation details.

$3

Each deployment platform runs final type checking during build:

- Railway: pnpm nx build slide-system - Full TypeScript compilation
- Vercel: npx nx build proxy-server - Serverless function validation
- GitHub Pages: npm run build - Vite build with type checking

Type errors at this stage prevent deployment entirely.

$3

#### TypeScript: Implicit Any
`typescript
// Problem
function process(data) { } // Parameter 'data' implicitly has an 'any' type

// Fix
function process(data: MessageData): void { }
`

#### TypeScript: Null/Undefined
`typescript
// Problem
const user = await getUser(id);
return user.name; // Object is possibly 'null'

// Fix
const user = await getUser(id);
if (!user) throw new Error('User not found');
return user.name;
`

#### Python: Missing Type Hints
`python


Problem

def process(data): # Function is missing a type annotation
return data

Fix

def process(data: Dict[str, Any]) -> Dict[str, Any]:
return data
`

$3

Comprehensive guides for type safety:

- Type Safety Best Practices - Best practices covering:
- TypeScript: Explicit types, avoiding any, type guards, generics
- Python: Type hints, TypedDict, Literal types, async typing
- Cross-language type synchronization process
- Common anti-patterns and how to avoid them
- Type safety checklists for code review

- Type Checking Guide - Implementation guide covering:
- Why type checking matters for each deployment platform
- Three-layer protection system (local hooks, CI/CD, production builds)
- Common type errors with detailed solutions
- Troubleshooting guide for CI failures
- Performance benchmarks and optimization tips
- Advanced topics (branded types, discriminated unions)

- Cross-Language Types - Type synchronization guide:
- TypeScript to Python type mapping reference
- Manual synchronization checklist
- Version tracking and changelog
- Known differences and limitations

📚 Documentation

$3

- API Documentation - Complete API reference
- Architecture Documentation - System design and data flow
- Railway Deployment Guide - Production deployment
- Monitoring Guide - Operational monitoring
- Troubleshooting Guide - Common issues and solutions
- Production Checklist - Deployment readiness

$3

- Phase 0 Setup Guide - Complete setup and verification
- Debugging Guide - Troubleshooting and CLI commands

$3

- Deployment Guide - Deployment configuration
- Build System Guide - Monorepo structure
- Development Guide - Development workflow
- Testing & Quality Guide - Testing practices
- Tavus Integration Guide - Tavus integration

$3

`bash


Run all tests

pnpm nx test

Run specific project tests

pnpm nx test proxy-server

Run tests with coverage

pnpm nx test --coverage

Run tests in watch mode

pnpm nx test --watch
`

🔧 Configuration

$3

`bash


API Configuration

TAVUS_API_KEY=your_api_key_here
TAVUS_BASE_URL=https://tavusapi.com

Development Configuration

NODE_ENV=development
PORT=3001

Vercel Configuration

ENABLE_EXPERIMENTAL_COREPACK=1
`

$3

The project uses Nx for build orchestration and dependency management. Key configuration files:

- nx.json - Nx workspace configuration
- package.json - Project dependencies and scripts
- tsconfig.base.json - Base TypeScript configuration
- pnpm-workspace.yaml` - pnpm workspace configuration