Blame for apps/api/README.md

# MicProtocol API

Production-ready NestJS backend for the MicProtocol podcast guest management platform.

## Features

### Core Capabilities
- 🔐 **Authentication**: Clerk JWT-based authentication with webhook support
- 🏢 **Multi-tenant Workspaces**: Organization-based access control with roles (Owner, Admin, Editor, Viewer)
- 🎙️ **Podcast Management**: Multiple podcasts per workspace with customizable settings
- 👤 **Guest Management**: Complete CRM for podcast guests with priority scoring
- 📧 **Outreach Automation**: Email sequences with templates, scheduling, and tracking
- 📅 **Scheduling**: Episode booking with calendar integration
- 📦 **Asset Collection**: Request and manage guest assets (headshots, bios, etc.)
- 🎬 **Content Studio**: Transcription and viral clip generation
- 📊 **Analytics**: Performance metrics and insights

### Technical Features
- 🔌 **tRPC + REST**: Type-safe APIs with Swagger documentation
- 📨 **Job Queues**: BullMQ for background processing (emails, transcription, exports)
- ⚡ **Caching**: Redis for session and data caching
- 🔍 **Search**: Meilisearch for fast guest/episodes search
- 🚀 **Production Ready**: Docker, health checks, rate limiting, comprehensive logging

## Quick Start

### Prerequisites
- Node.js >= 20.0.0
- PostgreSQL >= 15
- Redis >= 7
- pnpm >= 9.15.0

### Setup

```bash
# Install dependencies
pnpm install

# Setup environment
cp .env.example .env
# Edit .env with your credentials

# Generate Prisma client
pnpm db:generate

# Run database migrations
pnpm db:migrate

# Start development server
pnpm dev
```

### API Documentation

Once running, access the Swagger UI at: `http://localhost:4000/api/docs`

## API Endpoints

### Health & Monitoring
```
GET  /health              # Basic health check
GET  /health/detailed     # Full system health
GET  /health/ready        # Kubernetes readiness probe
GET  /health/live         # Kubernetes liveness probe
```

### Authentication
All endpoints require a Bearer token in the Authorization header:
```
Authorization: Bearer <clerk_jwt_token>
```

### Workspaces
```
GET    /api/v1/workspaces              # List user workspaces
POST   /api/v1/workspaces              # Create workspace
GET    /api/v1/workspaces/:id          # Get workspace details
PUT    /api/v1/workspaces/:id          # Update workspace
DELETE /api/v1/workspaces/:id          # Delete workspace
POST   /api/v1/workspaces/:id/members  # Invite member
```

### Podcasts
```
GET    /api/v1/workspaces/:id/podcasts     # List podcasts
POST   /api/v1/workspaces/:id/podcasts     # Create podcast
GET    /api/v1/workspaces/:id/podcasts/:id # Get podcast
PUT    /api/v1/workspaces/:id/podcasts/:id # Update podcast
DELETE /api/v1/workspaces/:id/podcasts/:id # Delete podcast
GET    /api/v1/workspaces/:id/podcasts/:id/stats # Podcast statistics
```

### Guests
```
GET    /api/v1/podcasts/:id/guests              # List guests with filters
POST   /api/v1/podcasts/:id/guests              # Create guest
POST   /api/v1/podcasts/:id/guests/bulk         # Bulk create
GET    /api/v1/podcasts/:id/guests/top-priority # Top priority guests
GET    /api/v1/podcasts/:id/guests/needs-follow-up # Follow-up needed
GET    /api/v1/podcasts/:id/guests/status-counts   # Status distribution
GET    /api/v1/podcasts/:id/guests/:id          # Get guest
PUT    /api/v1/podcasts/:id/guests/:id          # Update guest
PATCH  /api/v1/podcasts/:id/guests/:id/status   # Update status
DELETE /api/v1/podcasts/:id/guests/:id          # Delete guest
POST   /api/v1/podcasts/:id/guests/:id/tags     # Add tag
```

### Outreach
```
GET    /api/v1/podcasts/:id/outreach              # List sequences
POST   /api/v1/podcasts/:id/outreach              # Create sequence
GET    /api/v1/podcasts/:id/outreach/:id          # Get sequence
POST   /api/v1/podcasts/:id/outreach/:id/pause    # Pause sequence
POST   /api/v1/podcasts/:id/outreach/:id/resume   # Resume sequence
POST   /api/v1/podcasts/:id/outreach/:id/complete # Complete sequence
GET    /api/v1/podcasts/:id/outreach/stats        # Outreach statistics
```

## Priority Scoring Algorithm

Guests are automatically scored (0-100) based on:

| Factor | Weight | Description |
|--------|--------|-------------|
| Social Presence | 25% | LinkedIn, Twitter, YouTube presence |
| Professional Authority | 25% | Company prestige, title seniority |
| Engagement Potential | 25% | Speaker experience, thought leadership |
| Content Relevance | 15% | Topic alignment, expertise match |
| Availability | 10% | Current status and responsiveness |

## Job Queues

### outreach
- `send-email`: Send outreach emails via configured provider
- `schedule-message`: Schedule follow-up messages

### content
- `transcribe`: Audio transcription via Whisper
- `generate-clips`: AI-powered viral clip detection
- `export`: Platform-specific video rendering

### notifications
- `send-notification`: In-app and push notifications

### analytics
- `aggregate-stats`: Calculate and cache analytics

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `DATABASE_URL` | Yes | PostgreSQL connection string |
| `REDIS_HOST` | Yes | Redis server hostname |
| `REDIS_PASSWORD` | Yes | Redis password |
| `CLERK_SECRET_KEY` | Yes | Clerk authentication secret |
| `CLERK_PUBLISHABLE_KEY` | Yes | Clerk public key |
| `RESEND_API_KEY` | No | Email sending via Resend |
| `NVIDIA_NIM_API_KEY` | No | NVIDIA NIM AI features (transcription, clips) |
| `DEEPSEEK_API_KEY` | No | DeepSeek AI features (transcription, clips) |
| `MOONSHOT_API_KEY` | No | Moonshot AI features (transcription, clips) |
| `MEILISEARCH_HOST` | No | Search engine URL |

## Deployment

### Docker Compose

```bash
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f api

# Scale workers
docker-compose up -d --scale worker=3
```

### Production Checklist

- [ ] Change all default secrets
- [ ] Configure production database
- [ ] Set up SSL certificates
- [ ] Configure email provider
- [ ] Set up monitoring (Sentry, LogRocket)
- [ ] Configure backup strategy
- [ ] Set up CI/CD pipeline
- [ ] Review rate limiting settings

## Architecture

```
┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Next.js Web   │────▶│  NestJS API  │────▶│   PostgreSQL    │
│                 │     │              │     │                 │
└─────────────────┘     │  ┌────────┐  │     └─────────────────┘
                        │  │ tRPC   │  │              │
                        │  │ REST   │  │     ┌────────▼────────┐
                        │  │ Queue  │  │────▶│      Redis      │
                        │  └────────┘  │     │  (BullMQ/Jobs)  │
                        └──────────────┘     └─────────────────┘
```

## License

Private - All rights reserved.