# Slide System

**Automated presentation generation and control** - Motia.dev API backend deployed on Railway for BuzzTrail's Slidev-based demo system.

## 🚀 Production Deployment

**Live API Endpoint**: https://slide-system-production-5813.up.railway.app

The system is deployed on Railway with automatic deployments from the `main` branch.

## Overview

This Motia.dev application provides REST API endpoints for generating and controlling Slidev presentations in real-time. It integrates:
- **Motia.dev** for serverless-style API step functions
- **Railway** for production hosting and deployment
- **Supabase** for database and Realtime messaging (infrastructure now in `apps/supabase-backend/`)
- **GitHub Pages** for static presentation hosting
- **livekit** for video room infrastructure

> **Note**: Supabase infrastructure (migrations, Edge Functions) has been moved to `apps/supabase-backend/` as of Issue #179 (October 2024). This app now only contains Motia backend code.

## Architecture

```
apps/slide-system/
├── steps/                          # Motia API step definitions
│   ├── slidev-generate.step.ts     # Deck generation endpoint
│   ├── slidev-control.step.ts      # Control command endpoint
│   └── demo-session-create.step.ts # Session creation endpoint
├── Dockerfile                      # Production container
└── .env.motia                      # Local environment config
```

### System Architecture

```
┌─────────────┐     POST /api/slidev/generate    ┌──────────────┐
│ Pipecat     │────────────────────────────────▶│ slide-system │
│ Agent       │                                   │  (Railway)   │
└─────────────┘                                   └──────┬───────┘
                                                         │
       ┌─────────────────────────────────────────────────┼─────────────┐
       ▼                                                  ▼             ▼
┌──────────────┐                                  ┌──────────┐  ┌────────────┐
│   Supabase   │                                  │ Supabase │  │   GitHub   │
│  (metadata)  │                                  │ Realtime │  │   Pages    │
└──────────────┘                                  └────┬─────┘  └─────┬──────┘
                                                       │              │
                                                       ▼              ▼
                                              ┌────────────────────────────┐
                                              │  Customer Browser          │
                                              │  (Presentation + Realtime) │
                                              └────────────────────────────┘
```

## Getting Started

### Prerequisites

- pnpm package manager
- Docker (for local development)
- Railway account (for deployment)
- Supabase project configured
- Daily.co API key

### Local Development

1. **Set up environment variables** (`.env.motia`):
   ```bash
   DAILY_API_KEY=your_daily_api_key
   SUPABASE_URL=https://your-project.supabase.co
   SUPABASE_SERVICE_KEY=your_service_key
   ```

2. **Run locally with Motia**:
   ```bash
   cd apps/slide-system
   pnpx motia dev --port 3000
   ```

3. **Test the API**:
   ```bash
   curl -X POST http://localhost:3000/demo-sessions \
     -H "Content-Type: application/json" \
     -d '{"session_type":"test","environment":"dev"}'
   ```

### Production Deployment

See [RAILWAY-QUICKSTART.md](./RAILWAY-QUICKSTART.md) for deployment instructions.

## API Endpoints

### POST /api/slidev/generate

Generates a Slidev presentation deck and publishes it to GitHub Pages.

**Request**:
```json
{
  "sessionId": "uuid",
  "templateId": "starter",
  "data": {
    "company": "Acme Corporation",
    "tagline": "Building the future"
  }
}
```

**Response**:
```json
{
  "deckId": "abc1-def2-ghi3",
  "deckUrl": "https://buzztrail.github.io/buzztrail-presentations/abc1-def2-ghi3/",
  "message": "Deck generated successfully"
}
```

**Example**:
```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\":\"Test Corp\"}}"
```

### POST /api/slidev/control

Sends real-time control commands to presentations via Supabase Realtime.

**Request**:
```json
{
  "deckId": "abc1-def2-ghi3",
  "command": "next"
}
```

**Commands**: `next`, `prev`, `goto`, `first`, `last`

**Response**:
```json
{
  "success": true,
  "command": "next",
  "message": "Control command broadcast successfully"
}
```

**Example**:
```bash
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":"abc1-def2-ghi3","command":"next"}'
```

### POST /demo-sessions

Creates a demo session with Daily.co room and Supabase record.

**Request**:
```json
{
  "session_type": "test",
  "environment": "prod"
}
```

**Response**:
```json
{
  "session_id": "uuid",
  "daily_room_url": "https://buzztrail.daily.co/demo-xxxxx",
  "daily_room_name": "demo-xxxxx",
  "status": "waiting_for_customer",
  "created_at": "2025-10-08T10:13:11.403222+00:00"
}
```

## Performance

Based on production testing:

| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| Build Time | < 30s | ~15s | ✅ |
| Total Generation | < 90s | ~60s | ✅ |
| Control Latency | < 500ms | ~200ms | ✅ |
| Success Rate | > 95% | 100% | ✅ |
| Concurrent Capacity | 10+ | 15+ | ✅ |

## Environment Variables

### Required for Production (Railway)

```bash
# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your_service_role_key

# API Authentication
SLIDEV_API_KEY=your_generated_api_key

# Daily.co (for demo sessions)
DAILY_API_KEY=your_daily_api_key

# Optional
NODE_ENV=production
```

Set these in Railway dashboard → Variables tab or via CLI:
```bash
railway variables set SUPABASE_URL=https://your-project.supabase.co
railway variables set SUPABASE_SERVICE_KEY=your-key
railway variables set SLIDEV_API_KEY=your-key
```

### Railway Configuration

- **Root Directory**: `apps/slide-system`
- **Build**: Dockerfile (Motia.dev auto-detected)
- **Port**: Auto-assigned by Railway
- **Domain**: https://slide-system-production-5813.up.railway.app

## Database Schema

### Tables

**`conversation_sessions`** - Demo session metadata
- `id` (UUID, primary key)
- `session_type`, `status`, `daily_room_url`, `slidev_url`
- Tracks session state and lifecycle

**`slidev_decks`** - Generated deck metadata
- `id` (UUID, primary key)
- `deck_id` (TEXT, unique) - 12-char deck identifier
- `session_id` (UUID, foreign key)
- `template_id`, `generation_data`, `deck_url`, `html_content`

**`slide_control_commands`** - Real-time control commands
- `id` (UUID, primary key)
- `deck_id` (TEXT) - Links to slidev_decks
- `command` (TEXT) - Navigation command (next/prev/goto)
- `timestamp` (TIMESTAMPTZ)
- **Realtime enabled** for instant broadcasting

## Testing

### Performance Testing

```bash
# Run performance tests
npm run test:performance

# Run concurrent load tests
npm run test:concurrent

# Run end-to-end tests
npm run test:e2e
```

Test files located in `scripts/`:
- `performance-test.ts` - Sequential performance testing
- `concurrent-test.ts` - Concurrent load testing
- `test-utils.ts` - Shared test utilities

## Documentation

### Complete Documentation

- **[API Documentation](../../docs/api/slidev-api.md)** - Full API reference
- **[Architecture Documentation](../../docs/architecture/slidev-system.md)** - System architecture
- **[Railway Deployment Guide](../../docs/deployment/railway-deployment.md)** - Deployment instructions
- **[Monitoring Guide](../../docs/operations/monitoring.md)** - Production monitoring
- **[Troubleshooting Guide](../../docs/operations/troubleshooting.md)** - Common issues and solutions
- **[Production Checklist](../../docs/operations/production-checklist.md)** - Deployment readiness

### Quick Start Guides

- [Phase 0 Setup Guide](../../.claude/docs/phase0-setup-guide.md) - Initial setup and verification
- [Debugging Guide](../../.claude/docs/phase0-debugging-guide.md) - Troubleshooting and CLI commands

## Related Apps

- `apps/demos` - Customer-facing demo UI
- `apps/proxy-server` - API proxy and webhook handling
- `apps/backup-workflows` - Tavus backup workflows (separate system)

## Support

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

**Railway Status**: https://status.railway.app

**Supabase Status**: https://status.supabase.com
# Force Railway redeploy - enable bot spawning