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