BTG Rackham Video Sales Coach

A comprehensive meeting analysis application that uses AI to analyze sales meetings based on Neil Rackham's communication behavior framework. The system processes uploaded videos, performs speaker diarization, classifies behaviors, and provides actionable coaching feedback.

Project Status

✅ COMPLETE - 100% IMPLEMENTED

This is a fully functional, production-ready application!

Backend (100% Complete):

• ✅ Complete FastAPI application with async support
• ✅ MongoDB integration with Motor (async driver)
• ✅ JWT-based authentication system with HTTPOnly cookies
• ✅ Comprehensive API routes (auth, uploads, jobs, analyses)
• ✅ Single-concurrency job queue with FIFO processing
• ✅ TTL-based data retention (90 days)
• ✅ Gemini 2.5 Pro integration for video analysis
• ✅ Single-pass unified JSON generation
• ✅ JSON schema validation with up to 2 retry attempts
• ✅ Comprehensive Rackham behavior classification (11 behaviors)
• ✅ Pull:Push ratio calculations with transition detection
• ✅ Speaking time analysis
• ✅ Filler word detection
• ✅ Question quality metrics
• ✅ Clarity/Impact/Inclusion scoring
• ✅ Chunked upload system (up to 2GB)
• ✅ Video file assembly and storage
• ✅ Filename sanitization & path traversal prevention
• ✅ File type and size validation with security utilities
• ✅ WeasyPrint-based PDF reports with Jinja2 templates
• ✅ Docker containerization
• ✅ Comprehensive pytest test suite:
  • Validation tests
  • Route tests
  • PDF smoke tests
  • Security tests
  • Shared fixtures

Frontend (100% Complete):

• ✅ Vite + React + TypeScript setup
• ✅ TailwindCSS configuration with BTG theme
• ✅ TypeScript type definitions for all API models
• ✅ Complete API service layer (axios-based)
• ✅ Authentication context (React Context API)
• ✅ React Router with protected routes
• ✅ LoginPage - Email/password authentication
• ✅ RegisterPage - User registration
• ✅ Layout & Navigation - Responsive navigation with user menu
• ✅ UploadPage - Drag & drop with chunked upload, progress tracking
• ✅ ProcessingPage - Real-time job status monitoring with stepper UI
• ✅ DashboardPage - Complete analysis visualization:
  • Speaking time pie chart (Recharts)
  • Pull:Push visual gauges (overall meeting + per participant) with color-coded thresholds
  • Interactive timeline with all utterances, behavior classification, and timestamps
  • Pull→Push transition markers showing behavior changes over time
  • Inappropriate push flags warning when timing is suboptimal
  • Build-on indicators showing when proposals extend prior ideas
  • Behavior breakdowns (Pull vs Push categories)
  • Communication scores (Clarity/Impact/Inclusion) with progress bars
  • Coaching action items with clickable timestamps (jump to examples in timeline)
  • Alert system with severity levels
  • Overall feedback (strengths & opportunities)
  • PDF download button
• ✅ HistoryPage - Past analyses with 30/60/90 day filters
• ✅ Accessibility features (ARIA labels, keyboard navigation)

Infrastructure (100% Complete):

• ✅ Docker Compose setup (frontend, backend, MongoDB)
• ✅ Apache reverse proxy configuration
• ✅ Environment variable management
• ✅ .gitignore for project
• ✅ Comprehensive README with setup instructions

---

Architecture

┌─────────────────┐
│  React Frontend │  (Vite + TypeScript + TailwindCSS)
│  Port: 3000     │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│ Apache Proxy    │  (Existing server)
│ Port: 80/443    │
└────────┬────────┘
         │
         ↓ /api
┌─────────────────┐
│ FastAPI Backend │  (Python 3.11+)
│ Port: 8080      │
└────────┬────────┘
         │
         ├─→ MongoDB (Port: 27017)
         ├─→ Gemini 2.5 Pro API
         └─→ Local Storage (/data/videos)

---

Setup Instructions

Prerequisites

• Docker & Docker Compose
• Gemini API key (Get one here)
• Apache web server (you mentioned you already have this)

1. Clone and Configure

cd /path/to/rackham_meeting_analyzer

# Set up environment variables
cd infra
cp .env.example .env
nano .env  # Add your GEMINI_API_KEY and generate a JWT_SECRET

Generate a secure JWT secret:

openssl rand -base64 32

2. Start Services

cd infra
docker-compose up --build

This will start:

• Frontend on http://localhost:3000
• Backend on http://localhost:8080
• MongoDB on localhost:27017

3. Configure Apache (Optional)

If you want to access via your Apache server:

# Copy the sample config
sudo cp infra/apache/btg.conf /etc/apache2/sites-available/btg.conf

# Edit to match your domain
sudo nano /etc/apache2/sites-available/btg.conf

# Enable required modules
sudo a2enmod proxy proxy_http

# Enable the site
sudo a2ensite btg

# Restart Apache
sudo systemctl restart apache2

4. Access the Application

• Direct: http://localhost:3000
• Via Apache: http://btg.example.com (after configuring)
• API Docs: http://localhost:8080/docs

---

Development Workflow

Backend Development

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy and configure .env
cp .env.example .env
nano .env

# Run locally
uvicorn app.main:app --reload --port 8080

Frontend Development

cd frontend

# Install dependencies
npm install

# Run dev server
npm run dev

# Build for production
npm run build

MongoDB Access

# Connect to MongoDB shell
docker exec -it infra-mongo-1 mongosh btg

# View collections
show collections

# Query users
db.users.find()

# Query jobs
db.jobs.find()

---

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login
• POST /api/auth/logout - Logout
• GET /api/auth/me - Get current user

Uploads

• POST /api/uploads/init - Initialize chunked upload
• POST /api/uploads/chunk - Upload chunk
• POST /api/uploads/finish - Finalize upload

Jobs

• GET /api/jobs/:id - Get job status
• POST /api/jobs/:id/start - Start job processing

Analyses

• GET /api/analyses/:id - Get analysis JSON
• GET /api/analyses/:id/pdf - Download PDF report
• GET /api/analyses/?range=30 - Get history (30/60/90 days)

Full API documentation: http://localhost:8080/docs

---

Key Technologies Used

Backend:

• FastAPI (Python) - Modern async web framework
• MongoDB with Motor - Async database driver
• Gemini 2.5 Pro - AI video analysis
• WeasyPrint - PDF generation
• JWT - Authentication

Frontend:

• React 18 with TypeScript - UI framework
• Vite - Build tool
• TailwindCSS - Styling
• React Router - Navigation
• Recharts - Data visualization
• React Dropzone - File uploads
• Axios - HTTP client

---

Testing

Backend Tests

cd backend
pytest tests/

Frontend Tests

cd frontend
npm run test

---

Troubleshooting

Backend Issues

Job queue not processing:

• Check Gemini API key is valid
• Check video file exists in /data/videos
• View logs: docker logs infra-backend-1

MongoDB connection failed:

• Ensure MongoDB container is running
• Check MONGO_URL environment variable

Frontend Issues

API calls failing:

• Check backend is running on port 8080
• Verify VITE_API_BASE environment variable
• Check CORS settings in backend

Upload fails:

• Check file size (max 2GB)
• Verify file format (mp4, mov, avi, mkv)
• Check available disk space

---

Project Structure

rackham_meeting_analyzer/
├── backend/
│   ├── app/
│   │   ├── api/          # API route handlers
│   │   ├── core/         # Config, dependencies
│   │   ├── models/       # Data models
│   │   ├── schemas/      # JSON schemas
│   │   ├── services/     # Business logic
│   │   ├── templates/    # PDF templates
│   │   └── main.py       # FastAPI app
│   ├── tests/            # Backend tests
│   ├── Dockerfile
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── pages/        # Page components ✓
│   │   ├── components/   # Reusable components ✓
│   │   ├── contexts/     # React contexts ✓
│   │   ├── services/     # API services ✓
│   │   ├── types/        # TypeScript types ✓
│   │   └── App.tsx       # Main app ✓
│   ├── Dockerfile ✓
│   ├── package.json
│   └── tailwind.config.js ✓
├── infra/
│   ├── apache/
│   │   └── btg.conf      # Apache config ✓
│   ├── docker-compose.yml ✓
│   └── .env.example ✓
└── docs/
    └── btg-rackham-video-coach-dev-plan-python-single-pass.md

---

Security Notes

• JWT tokens stored in HTTPOnly cookies
• File upload validation (size, type)
• TTL-based data expiration (90 days)
• CORS restricted to configured origins
• Reminder: Internal meetings only

---

Ready to Deploy!

The application is 100% complete and ready for production use. Here are suggested next steps:

1. Initial Setup

   • Add your Gemini API key to .env
   • Start the services with docker-compose up
   • Create your first user account
   • Test with a sample meeting video

2. Production Deployment (Optional enhancements)

   • Configure SSL certificates for HTTPS
   • Set up monitoring and logging (e.g., Grafana, Prometheus)
   • Configure automated backups for MongoDB
   • Optimize Docker builds for production

3. Fine-tuning (Optional)

   • Adjust Gemini prompts based on real-world results
   • Customize BTG theme colors
   • Add custom branding

4. Phase 2 Features (Future enhancements)

   • Resume uploads for large files
   • Multi-concurrency processing
   • Team rollup reports with anonymization
   • Calendar integrations (Google Calendar, Outlook)
   • Slack/Teams notifications
   • Advanced analytics and trends

---

Support & Resources

• FastAPI Docs: https://fastapi.tiangolo.com/
• React Docs: https://react.dev/
• TailwindCSS: https://tailwindcss.com/docs
• Gemini API: https://ai.google.dev/docs
• Rackham Framework: See docs/btg-rackham-video-coach-dev-plan-python-single-pass.md

---

License

Internal use only - BTG Rackham Video Sales Coach

---

Built with Claude Code