buzztrail

v1.0.0

Published

2 months ago

BuzzTrail Chrome Extension and Website Script - AI companion for web browsing

0High
0Medium
0Low

larsbuzz

chrome-extension ai chatbot typescript wxt

BuzzTrail

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

🚀 Current Focus: Slidev Control System - PRODUCTION READY ✅

Slidev System: DEPLOYED AND OPERATIONAL ✅

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

What's Been Built

✅ 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

Quick Start - Using the Slidev API

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.

Key Features

✅ 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

System Architecture

┌──────────────────┐
│  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)  │
                    └──────────────────┘

Applications

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

Prerequisites

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

Installation

# Install dependencies
pnpm install

# Verify Nx installation
pnpm nx --version

🚀 Deployment

Vercel Deployment (Current Focus)

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

Local Development

# 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]

Production Build

# 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.

Why Type Checking Matters

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.

Quick Reference

# 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

Local Development - Pre-commit Hooks

Husky automatically runs type checks on every commit:

TypeScript type checking (affected files only)
ESLint type-aware linting (affected files only)
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):

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

CI/CD Pipeline - Automated Validation

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

1. TypeScript Type Checking

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

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

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.

Production Builds - Final Gate

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.

Common Type Errors and Quick Fixes

TypeScript: Implicit Any

// Problem
function process(data) { } // Parameter 'data' implicitly has an 'any' type

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

TypeScript: Null/Undefined

// 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

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

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

Documentation

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

Slidev System (Production)

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

Infrastructure Setup

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

General Development

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

Running Tests

# 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

Environment Variables

# 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

Nx Configuration

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