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

# 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

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