# MicProtocol – System Architecture
## Philosophy
MicProtocol is a **modular monolith** with clear bounded contexts, designed to split into microservices once specific domains hit scale. The architecture prioritizes workflow automation over simple CRUD, recognizing that significant time savings come from eliminating friction in asynchronous coordination between hosts, guests, and production teams.
## Tech Stack
| Layer | Technology | Justification |
|-------|-----------|---------------|
| **Monorepo** | Turborepo + pnpm workspaces | Shared types, UI components, and validation schemas across web/mobile |
| **Backend** | NestJS (Node.js) | Enterprise-grade DI, built-in CQRS/Event Sourcing support, gradual microservice migration |
| **API Protocol** | tRPC + WebSockets | End-to-end type safety between frontend and backend; real-time updates for scheduling |
| **Database** | PostgreSQL 15+ (primary) + Redis | ACID for financial/booking data; Redis for session, cache, and BullMQ job queues |
| **ORM** | Prisma | Type-safe migrations, excellent relations handling for complex guest-episode-asset graphs |
| **Search** | Meilisearch | Instant guest lookup, fuzzy matching on names/companies |
| **Storage** | Cloudflare R2 (S3-compatible) | Zero egress fees for media sharing; perfect for audio files and headshots |
| **Queue** | BullMQ (Redis-backed) | Reliable scheduling of follow-up emails, reminder workflows |
| **AI Layer** | NVIDIA NIM + DeepSeek + Moonshot | Outreach personalization, audiogram generation, transcript processing |
| **CLIP Scoring** | Python + OpenCLIP + bart-large-mnli | Multimodal clip evaluation (visual/audio/transcript) via subprocess |
| **Web Frontend** | Next.js 14 (App Router) | Server Components for heavy dashboards; Edge runtime for guest portal |
| **Mobile** | React Native (Expo) | 70% code reuse with web, native calendar integration |
| **Auth** | Clerk | Handles OAuth (Google/Apple), MFA, and session management |
| **Calendar** | Nylas API | Unified Google/Outlook/Exchange integration; bi-directional sync |
| **Email** | Resend + React Email | Programmable transactional emails with React components |
## System Architecture
```mermaid
graph TB
subgraph "Client Layer"
WEB[Next.js 14 Web App
App Router]
MOBILE[React Native
Expo SDK]
GUEST_PORTAL[Guest Portal
Next.js Edge Runtime]
end
subgraph "API Gateway Layer"
GW[NestJS API Gateway
tRPC Router]
WS[WebSocket Gateway
Socket.io]
end
subgraph "Core Domains - Modular Monolith"
AUTH[Auth Module]
GUEST[Guest Management
Domain]
OUTREACH[Outreach Automation
Domain]
SCHEDULE[Scheduling Engine
Domain]
ASSETS[Asset Pipeline
Domain]
RECORDING[Recording Infrastructure
Domain]
CONTENT_STUDIO[Content Studio
CLIP Scoring]
ANALYTICS[Analytics Engine]
end
subgraph "Infrastructure Layer"
DB[(PostgreSQL
Primary Data)]
CACHE[(Redis
BullMQ + Cache)]
SEARCH[(Meilisearch)]
OBJ_STORE[(R2 Object Storage)]
end
subgraph "ML Pipeline"
CLIP[CLIP Scorer
Python + OpenCLIP]
FF[FFmpeg
Frame/Audio Extract]
end
subgraph "External Integrations"
CAL[Calendar APIs
Nylas/Google/Outlook]
EMAIL[Email Providers
Resend/SendGrid]
AI[NVIDIA NIM + DeepSeek + Moonshot]
PODCAST_HOST[Podcast Hosting
Buzzsprout/Transistor]
end
WEB -->|tRPC| GW
MOBILE -->|tRPC| GW
GUEST_PORTAL -->|Public REST| GW
GW --> AUTH
GW --> GUEST
GW --> OUTREACH
GW --> SCHEDULE
GW --> ASSETS
GW --> RECORDING
GW --> CONTENT_STUDIO
GW --> ANALYTICS
GUEST --> DB
GUEST --> SEARCH
OUTREACH --> DB
OUTREACH --> CACHE
SCHEDULE --> DB
SCHEDULE --> CAL
ASSETS --> DB
ASSETS --> OBJ_STORE
RECORDING --> DB
RECORDING --> OBJ_STORE
OUTREACH --> EMAIL
ASSETS --> AI
ANALYTICS --> DB
CONTENT_STUDIO --> CLIP
CONTENT_STUDIO --> OBJ_STORE
CLIP --> FF
CACHE -->|BullMQ Workers| EMAIL
CACHE -->|BullMQ Workers| OBJ_STORE
CACHE -->|BullMQ Workers| CAL
style GUEST_PORTAL fill:#e1f5e1
style WS fill:#fff3e0
```
## Bounded Contexts
### Guest Management Domain
Owns the guest lifecycle from prospect to published. Manages guest profiles, tags, priority scoring, and status transitions.
### Outreach Automation Domain
Manages email sequences, message tracking (sent/opened/clicked), and AI-powered personalization. Primary candidate for future microservice extraction due to high write volume on email events.
### Scheduling Engine Domain
Handles episode creation, booking management, calendar integration (Nylas), and recording session coordination.
### Asset Pipeline Domain
Manages the pre-production asset collection workflow: requesting materials from guests (headshots, bios, audio intros), tracking submissions, and processing uploads through AI validation.
### Recording Infrastructure Domain
Provides a highly resilient, local-first double-ender audio recording system tailored for low-bandwidth environments (e.g., Africa). It handles environmental diagnostics (Green Room API), asynchronous chunked 48kHz audio uploading, OPUS fallback codecs, and BullMQ worker-based edge post-processing.
### Analytics Engine
Aggregates metrics across all domains: guest pipeline funnel, outreach performance (open/click rates), scheduling efficiency, and asset completion tracking.
### Content Studio Domain
Provides viral clip detection, scoring, and multi-platform export. Integrates with the CLIP scoring engine (Python subprocess) to evaluate clips on visual composition, audio quality, and transcript engagement. Handles clip approval workflow and scheduled exports.
## Project Structure
```
MicProtocol/
├── apps/
│ ├── api/ # NestJS backend
│ │ ├── prisma/ # Database schema & migrations
│ │ └── src/
│ │ ├── analytics/ # Analytics domain module
│ │ ├── assets/ # Asset pipeline domain module
│ │ ├── auth/ # Clerk authentication
│ │ ├── guest/ # Guest management domain module
│ │ ├── outreach/ # Outreach automation domain module
│ │ ├── prisma/ # Database service
│ │ ├── queue/ # BullMQ workers (content, clip-scoring)
│ │ ├── recording/ # Recording infrastructure domain & edge processing
│ │ ├── content-studio/ # Viral clip detection + scoring + export
│ │ ├── scheduling/ # Scheduling engine domain module
│ │ ├── trpc/ # tRPC router setup
│ │ └── websocket/ # Real-time events
│ └── web/ # Next.js 14 frontend
│ └── src/
│ ├── app/
│ │ ├── (dashboard)/ # Protected host workspace
│ │ └── (guest-portal)/ # Public guest-facing pages
│ ├── lib/ # tRPC client, providers
│ └── styles/ # Design system CSS
├── services/
│ └── clip-scorer/ # Python ML engine (CLIP + audio + NLP)
│ ├── scoring/ # Visual, audio, transcript modules
│ ├── pipeline.py # CLI entrypoint
│ ├── pyproject.toml # uv-managed dependencies
│ └── Dockerfile
├── packages/
│ ├── shared-types/ # Domain enums, Zod schemas
│ ├── ui/ # Design tokens
│ ├── eslint-config/ # Shared linting
│ └── tsconfig/ # Shared TS configs
└── docs/ # Architecture documentation
```