Spaces:
Running
Running
| # 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. | |