**MicProtocol** # Technical Architecture & Design Blueprint *Podcast Guest Management Platform for Africa* Version 1.0 | Lead Engineer Design Document | 2026 **Confidential --- Internal Distribution Only** --- ## 1. Executive Architecture Overview MicProtocol is a domain-driven, event-sourced podcast guest management platform purpose-built for the African podcasting ecosystem. Podcasters across Kenya, Nigeria, South Africa, Ghana and the broader continent currently spend 20--30% of their productive time on manual guest coordination --- a friction-heavy mix of email chasing, calendar juggling, asset collection, and follow-up. MicProtocol eliminates this waste through workflow automation, intelligent defaults, and asynchronous coordination tooling. ### 1.1 Core Philosophy The platform is architected as a modular monolith with clearly bounded contexts, designed to be split into independent microservices as individual domains hit scale. For example, the Outreach Automation domain is built as a fully isolated module from day one, anticipating its eventual extraction into a standalone product or API offering. > **Design Principle:** The 20--30% time savings does not come from replacing the host's workflow. It comes from compressing the asynchronous gaps between decision points through automation and intelligent defaults. ### 1.2 African Market Considerations The architecture explicitly accounts for the realities of the African technology environment: - **Bandwidth constraints:** Asset uploads are chunked and resumable; the guest portal runs on Cloudflare Edge for low-latency access from Nairobi, Lagos, Accra, and Johannesburg. - **Mobile-first reality:** React Native app with offline queue (WatermelonDB) supports hosts in areas with intermittent connectivity. - **WhatsApp integration path:** The outreach engine is designed to plug into WhatsApp Business API as a first-class channel alongside email, reflecting actual communication patterns across Africa. - **Multi-currency billing:** Workspace billing supports KES, NGN, ZAR, GHS with Flutterwave/Paystack as primary payment processors (alongside Stripe for international users). - **Timezone diversity:** All scheduling operations are timezone-aware from schema level, with defaults for WAT, EAT, CAT, and SAST. --- ## 2. Technology Stack Rationale Every technology choice is justified against the specific constraints of a bootstrapped-to-scale African SaaS product --- cost efficiency, developer availability, operational simplicity, and the ability to move fast without accumulating technical debt. | **Layer** | **Technology** | **Justification** | |-----------|---------------|-------------------| | Monorepo | Turborepo + pnpm workspaces | Shared types, UI components, and Zod validation schemas across web/mobile apps --- single source of truth | | Backend | NestJS (Node.js) | Enterprise-grade dependency injection, built-in CQRS/Event Sourcing support, gradual microservice migration path | | API Protocol | tRPC + WebSockets | End-to-end type safety between frontend and backend; real-time updates for scheduling and notifications | | Database | PostgreSQL 15+ | ACID guarantees for booking and financial data; JSON columns for flexible guest metadata | | Cache / Queue | Redis + BullMQ | Session management, response caching, and reliable scheduled job execution (follow-up emails, reminders) | | ORM | Prisma | Type-safe migrations with excellent graph-relation handling for guest-episode-asset relationships | | Search | Meilisearch | Instant guest lookup with fuzzy name/company matching; self-hostable for cost control | | Storage | Cloudflare R2 (S3-compatible) | Zero egress fees for media sharing --- critical for audio files and headshots at scale | | Web Frontend | Next.js 14 (App Router) | Server Components for heavy dashboards; Edge Runtime for guest portal (global low-latency) | | Mobile | React Native (Expo) | 70% code reuse with web via shared UI library; native calendar integration on iOS and Android | | Auth | Clerk | Handles OAuth (Google/Apple), MFA, and session management out of the box | | Calendar | Nylas API | Unified Google Calendar, Outlook, and Exchange integration with bi-directional sync | | Email | Resend + React Email | Programmable transactional emails using React components for rich, branded templates | | AI Layer | NVIDIA NIM + DeepSeek + Moonshot | Outreach personalization, audiogram generation, transcript processing, and asset validation | | Payments | Flutterwave / Paystack | Primary processors for KES, NGN, ZAR markets with mobile money support (M-Pesa, Airtel Money) | | CI/CD | GitHub Actions + Turborepo Cache | Remote caching reduces build times by ~80% in monorepo builds | --- ## 3. Domain-Driven Design Architecture The system is structured around five bounded contexts. Each context owns its data, its business logic, and its event contracts. Cross-context communication happens exclusively through domain events published to an internal event bus (NestJS EventEmitter in the monolith phase, NATS/Kafka in the microservices phase). ### 3.1 Bounded Contexts | **Domain** | **Responsibility** | **Key Aggregates** | **Scale Trigger** | |------------|-------------------|-------------------|-------------------| | Guest Management | Core CRM: guest profiles, tags, pipeline status, custom fields | Guest, Tag, GuestNote | Extract when >50K guests across platform | | Outreach Automation | Email/WhatsApp sequence management, delivery tracking, A/B testing | OutreachSequence, OutreachMessage, Template | Extract when email volume exceeds 100K/day | | Scheduling Engine | Calendar sync, booking management, availability resolution | Booking, AvailabilitySlot, CalendarIntegration | Extract when calendar operations exceed 500ms P95 | | Asset Pipeline | File collection, AI processing, approval workflows | AssetRequest, AssetSubmission, ProcessingJob | Extract when storage operations exceed 1TB/month | | Analytics Engine | Time-to-book metrics, outreach conversion, episode ROI | DailySnapshot, FunnelMetric, GuestScore | Extract when query time exceeds 2s P95 | ### 3.2 Event Sourcing Strategy Critical state transitions are recorded as immutable domain events rather than simple database updates. This provides a complete audit trail, enables time-travel debugging, and supports powerful analytics. Core domain events emitted by the Guest Management context: - **GuestCreated** --- fired on pipeline entry; triggers AI enrichment job - **GuestStatusChanged** --- fired on all status transitions; feeds analytics snapshots - **OutreachSequenceStarted** --- triggers the BullMQ scheduler for follow-up cadence - **BookingConfirmed** --- triggers calendar sync, welcome email, and asset collection portal creation - **AssetCollectionCompleted** --- triggers host notification and episode status advance - **EpisodePublished** --- triggers post-production promotional task generation ### 3.3 CQRS Pattern Read and write operations are separated at the handler level. Write operations go through Command Handlers that validate invariants and emit events. Read operations use dedicated Query Handlers that can target optimised read models or denormalised views without polluting the write model. > **Example:** The Guest Kanban Board uses a denormalised Redis-cached read model (refreshed on GuestStatusChanged events) to achieve sub-50ms query times, even with thousands of guests in a podcast pipeline, without slowing down write operations. --- ## 4. Database Schema Design The PostgreSQL schema is designed around the following key principles: guest uniqueness is per-podcast (not global), allowing the same person to appear on multiple shows; outreach sequences are state machines enabling A/B cadence testing; and asset requests are template-driven so podcasts can define required assets per episode type. ### 4.1 Core Schema Tables | **Table** | **Primary Key** | **Key Columns** | **Index Strategy** | |-----------|----------------|-----------------|-------------------| | users | uuid id | email (UK), encrypted_password, profile (JSON), default_timezone | B-tree on email; GIN on profile JSON | | workspaces | uuid id | name, slug (UK), billing_settings (JSON), owner_id (FK) | B-tree on slug; FK index on owner_id | | podcasts | uuid id | workspace_id (FK), title, rss_feed_url, recording_settings (JSON), outreach_defaults (JSON) | FK index on workspace_id; GIN on recording_settings | | guests | uuid id | podcast_id (FK), email, full_name, company, title, social_links (JSON), bio, status (enum), priority_score, last_contact_at, custom_fields (JSON) | Composite unique (podcast_id, email); B-tree on status; B-tree on priority_score; GIN on custom_fields | | outreach_sequences | uuid id | guest_id (FK), status (enum), template_id (FK), current_step, started_at | FK indexes on guest_id, template_id; B-tree on status | | outreach_messages | uuid id | sequence_id (FK), type (enum), subject, body_html, body_text, sent_at, opened_at, clicked_at, metadata (JSON) | FK on sequence_id; B-tree on sent_at; partial index on opened_at WHERE opened_at IS NOT NULL | | episodes | uuid id | podcast_id (FK), guest_id (FK), title, status (enum), scheduled_at, duration_minutes, host_notes, guest_instructions, recording_platform | FK indexes; B-tree on scheduled_at; B-tree on status | | bookings | uuid id | episode_id (FK), calendar_event_id, start_time, end_time, timezone, meet_link, calendar_provider_data (JSON), is_confirmed | UK on calendar_event_id; FK on episode_id; B-tree on start_time | | asset_requests | uuid id | episode_id (FK), type (enum), is_required, instructions, due_date | FK on episode_id; B-tree on due_date | | asset_submissions | uuid id | request_id (FK), file_url, file_type, file_size, status (enum), submitted_at | FK on request_id; B-tree on status | ### 4.2 Row-Level Security (RLS) Policy PostgreSQL RLS is enabled on every table containing user data. Workspace-scoped policies ensure complete data isolation between customers without application-layer enforcement. ```sql -- Example RLS policy: Workspace data isolation CREATE POLICY workspace_isolation ON guests USING (podcast_id IN ( SELECT id FROM podcasts WHERE workspace_id = current_setting('app.workspace_id')::uuid )); ``` ### 4.3 Guest Status Enum The guest status field follows a strict state machine --- invalid transitions are rejected at the database constraint level AND at the domain service level (defence in depth): | **Status** | **Entry Conditions** | **Exit Transitions** | **Automated Actions** | |------------|---------------------|---------------------|---------------------| | prospect | Manual entry or CSV import | → ai_research (auto), → snoozed (manual) | Trigger AI enrichment job | | ai_research | AI enrichment job running | → ready_to_contact (auto on completion) | Fetch LinkedIn, Twitter, recent content | | ready_to_contact | AI enrichment complete | → outreach_sent (auto/manual) | Enable outreach sequence selection | | outreach_sent | Sequence triggered | → opened, → bounced, → no_response | Start BullMQ tracking watchdog | | opened | Tracking pixel fired | → replied, → no_response (3 days) | Log engagement timestamp | | replied | Inbound email parsed | → interested, → declined, → questions | AI sentiment analysis on reply | | interested | Positive intent detected | → scheduling_link_sent (auto) | Generate scheduling token and send link | | confirmed | Calendar event created | → pre_production (auto) | Send welcome packet, create asset requests | | pre_production | Booking confirmed | → assets_collected (auto) | Daily asset completion reminders | | recorded | Host marks complete | → post_production (manual) | Archive recording, notify editor | | published | Episode goes live | → promotion_active (auto) | Generate clips, social media tasks | | completed | Promotional period ends | Terminal state | Archive guest record, update analytics | --- ## 5. API Architecture ### 5.1 tRPC Router Organisation The tRPC router mirrors the domain structure. Each domain exposes a typed router that is merged into the root application router. All inputs are validated with Zod schemas shared between frontend and backend via the shared package in the monorepo. ```typescript // packages/api/src/router/index.ts export const appRouter = createTRPCRouter({ auth: authRouter, // session, OAuth callbacks guests: guestRouter, // CRUD, bulk ops, AI enrichment outreach: outreachRouter, // sequences, templates, analytics schedule: scheduleRouter, // availability, bookings, calendar sync assets: assetRouter, // presigned URLs, submissions, approval analytics: analyticsRouter, // dashboards, exports, snapshots podcast: podcastRouter, // workspace podcasts config }); ``` ### 5.2 Guest Portal REST API The guest-facing portal uses a minimal public REST API (not tRPC) to keep the bundle lightweight. All endpoints are authenticated via short-lived signed tokens embedded in email links --- no account creation required for guests. | **Method** | **Endpoint** | **Auth** | **Description** | |------------|-------------|----------|----------------| | GET | /portal/booking/:token | Signed token | Fetch available scheduling slots | | POST | /portal/booking/:token/confirm | Signed token | Confirm a selected time slot | | GET | /portal/upload/:token | Signed token | Fetch asset request requirements | | POST | /portal/upload/:token/file | Signed token | Initiate chunked file upload (presigned R2 URL) | | PATCH | /portal/upload/:token/submit | Signed token | Mark asset submission complete | | GET | /portal/episode/:token | Signed token | Fetch episode briefing and recording instructions | ### 5.3 WebSocket Events Real-time updates are delivered via Socket.io namespaces scoped to workspace ID. This enables live kanban board updates, instant notification of guest replies, and recording session status without polling. | **Event** | **Direction** | **Payload** | **Consumer** | |-----------|--------------|-------------|--------------| | guest:status_changed | Server → Client | { guestId, oldStatus, newStatus, timestamp } | Kanban board auto-refresh | | outreach:email_opened | Server → Client | { messageId, guestId, openedAt } | Outreach activity feed | | booking:confirmed | Server → Client | { episodeId, startTime, guestName } | Dashboard notification banner | | asset:submitted | Server → Client | { requestId, assetType, guestName } | Episode production checklist | | recording:session_ready | Server → Client | { episodeId, meetLink } | Host pre-recording alert | --- ## 6. Frontend Architecture ### 6.1 Next.js 14 Application Structure The web application uses the App Router with a clear separation between the authenticated host dashboard and the public guest portal. Server Components handle data-heavy views; Client Components handle interactive elements. ``` app/ ├── (dashboard)/ # Protected host workspace │ ├── podcasts/ │ │ ├── [id]/ │ │ │ ├── guests/ # Kanban board (dnd-kit) │ │ │ ├── schedule/ # Calendar view (React Big Calendar) │ │ │ └── episodes/ # Table with filters (TanStack Table) │ │ └── page.tsx # Podcast list (Server Component) │ ├── outreach/ # Email template builder (Tiptap editor) │ └── settings/ # Integration configs (Calendar, Email) ├── (guest-portal)/ # Public-facing, minimal bundle │ ├── booking/[token]/ # Self-service scheduling (Cal.com-style) │ └── upload/[token]/ # Drag-drop asset upload (react-dropzone) └── api/trpc/[trpc]/route.ts # tRPC handler (Edge Runtime) ``` ### 6.2 State Management Strategy | **State Type** | **Solution** | **Scope** | **Rationale** | |----------------|-------------|-----------|---------------| | Server state | tRPC + TanStack Query | Global | Automatic caching, background refetching, optimistic updates | | Client UI state | Zustand | Component trees | Lightweight, no boilerplate; used for kanban selection, filter state | | Form state | React Hook Form + Zod | Form scope | Schema shared with backend; instant validation without round-trips | | Real-time state | Socket.io client + Zustand | Global | WebSocket events update Zustand slices, which invalidate TanStack Query caches | | Offline state (mobile) | WatermelonDB | Device | Queues outreach sends and status updates when host is offline | ### 6.3 Key UI Components The following bespoke components are required beyond the standard component library (shadcn/ui base): - **GuestKanban** --- drag-and-drop board using dnd-kit with optimistic status transitions, virtual scrolling for large pipelines, and bulk action toolbar - **OutreachComposer** --- rich text editor built on Tiptap with merge tag support ({guest_name}, {podcast_name}, {icebreaker}), send-time optimisation suggestions, and preview rendering - **SchedulingCalendar** --- multi-timezone slot picker backed by Nylas availability API, with host buffer time enforcement and guest preference capture - **AssetUploadPortal** --- chunked file upload with progress indication, real-time quality validation feedback (image resolution check, audio quality meter), and mobile camera capture - **EpisodeBriefCard** --- guest-facing episode briefing with recording instructions, tech requirements checklist, and one-click calendar add ### 6.4 Mobile Application (React Native + Expo) The mobile app targets podcast hosts who need to manage their guest pipeline from their phone --- common in the African context where mobile is the primary device. The app shares 70% of its logic with the web application via the monorepo shared packages. - Tamagui for cross-platform UI components (shared primitive layer with web) - Expo Router for file-based navigation (mirrors Next.js routing mental model) - react-native-calendar-events for native iOS/Android calendar read/write - Expo Notifications for deep-linked push notifications (tap reply alert → open guest profile) - WatermelonDB for offline data persistence and sync queue - iOS 3D Touch Quick Actions: 'Mark as Recorded', 'Send Follow-up', 'Open Calendar' --- ## 7. AI & Automation Layer The AI layer is the primary competitive moat. The database and workflow engine are table stakes --- the automation intelligence is what makes MicProtocol defensible. ### 7.1 Smart Outreach Personalisation Every outreach email is personalised using a three-step enrichment pipeline triggered automatically when a guest enters the pipeline: 1. Web scraper (Puppeteer/Bright Data) collects the guest's 3 most recent LinkedIn posts, 5 most recent tweets, and latest blog article or podcast appearance 2. GPT-4 generates a 2-sentence personalised icebreaker referencing a specific recent achievement or comment 3. The icebreaker is injected into the selected outreach template via the {icebreaker} merge tag > **Personalisation impact data from comparable B2B outreach tools:** personalised emails see 2.4x higher reply rates vs. generic templates. For podcast outreach, where the ask (committing 1-2 hours) is significant, personalisation is critical to conversion. ### 7.2 Automated Asset Validation When guests upload assets via the portal, automated validation runs immediately before the host ever reviews the submission: | **Asset Type** | **Validation Check** | **AI Model** | **Auto-Action on Failure** | |----------------|---------------------|--------------|---------------------------| | Headshot | Resolution ≥ 1200×1200px, face detection, background complexity | Google Vision API | Reject with specific guidance: 'Please use a photo with a plain background' | | Headshot | Background removal quality | Remove.bg API | Auto-process: generate clean version and present both for approval | | Intro audio | Audio quality (SNR > 20dB), duration 15-60 seconds | Custom FFmpeg pipeline | Reject with recording tips if noisy; flag if outside duration range | | Intro audio | Name pronunciation verification | Whisper transcription | Flag for host review if host name mispronounced | | Social links | URL validity and public accessibility | Puppeteer headless check | Reject invalid/private links with correction prompt | | Bio text | Minimum 50 words, no HTML injection, LinkedIn vs. submitted consistency | GPT-4 comparison | Suggest expanded bio if too short; sanitise HTML | ### 7.3 Predictive Scheduling A lightweight ML model (TensorFlow.js, deployed as a serverless function) suggests optimal recording time slots based on three signals: - Guest timezone and inferred working hours (from email open timestamps and social activity patterns) - Host's historical energy and preparation patterns (derived from post-episode self-rating scores stored in episode metadata) - Audience engagement correlation: episodes recorded at certain times of day historically produce better engagement --- the model surfaces this insight during slot selection ### 7.4 AI-Generated Episode Assets Post-recording, the asset pipeline uses AI to generate promotional materials automatically: - Whisper transcription of full recording → structured show notes with timestamps and chapter markers - GPT-4 generates 3 social media post variants (Twitter/X, LinkedIn, Instagram) with guest tagging handles - Audiogram generation: Whisper identifies the 60-second highlight clip, FFmpeg generates waveform visualisation, React Server Component renders branded template - Quote card generation: GPT-4 extracts 5 quotable moments, Canvas API renders branded image variants --- ## 8. Integration Architecture ### 8.1 Calendar Integration (Nylas API) Nylas provides a unified abstraction over Google Calendar, Outlook, and Exchange --- handling OAuth flows, webhook subscriptions, and event CRUD without building separate integrations for each provider. | **Integration Flow** | **Trigger** | **Actions** | **Error Handling** | |---------------------|-------------|-------------|-------------------| | Availability fetch | Host opens scheduling view | Query Nylas for busy/free slots across next 4 weeks, apply buffer rules | Cache stale data; surface 'calendar unavailable' state | | Guest books slot | Guest submits booking form | Create calendar event via Nylas; add Zoom/Meet link; send ICS to both parties | Retry 3× with exponential backoff; fallback to manual confirmation | | Booking modified | Guest/host reschedules | Update Nylas event; re-send ICS; update booking record; notify both parties | Conflict detection before update; surface to host if conflict found | | Calendar webhook | External calendar change detected | Nylas pushes event update; Scheduling Engine reconciles with booking record | Idempotent processing via event ID deduplication | ### 8.2 Email Integration (Resend + React Email) All transactional emails are built as React components in the packages/email package and rendered server-side by Resend. This enables type-safe, version-controlled email templates with full preview in development. - **OutreachEmail** --- personalised initial contact with icebreaker, podcast description, and scheduling CTA - **FollowUpEmail** --- gentle 3-day and 7-day follow-ups with social proof (recent guest names) - **BookingConfirmationEmail** --- calendar attachment, recording instructions, asset upload link - **AssetReminderEmail** --- 7-day, 3-day, and day-before reminders with completion percentage - **EpisodeLiveEmail** --- notification when episode publishes with social sharing assets > All emails include automatic unsubscribe handling (CAN-SPAM compliant), list-unsubscribe headers, and GDPR-compliant footer. Unsubscribe events update the guest record status to prevent future automated sends. ### 8.3 WhatsApp Business API (Africa-First Channel) Given that WhatsApp is the dominant communication channel across Africa, the Outreach Automation domain is designed with WhatsApp as a first-class channel from day one, not an afterthought: - Initial outreach: WhatsApp template message (pre-approved by Meta) sent when email goes unopened after 48 hours - Booking confirmation: WhatsApp message with calendar attachment and recording link - Day-before reminder: WhatsApp message with recording instructions and tech checklist - Reply handling: Inbound WhatsApp replies are captured via webhook and surfaced in the host's unified inbox --- ## 9. Security & Compliance Architecture ### 9.1 Data Security | **Concern** | **Implementation** | **Standard** | |-------------|-------------------|--------------| | Authentication | Clerk with MFA enforcement, session expiry, device management | OWASP A07 | | Data isolation | PostgreSQL RLS policies scoped to workspace_id application setting | Tenant isolation | | Transport security | TLS 1.3 minimum on all connections; HSTS with preload | OWASP A02 | | File uploads | Presigned R2 URLs with 15-minute expiry; ClamAV virus scan on ingest; MIME type verification | OWASP A08 | | Secrets management | Environment variables via AWS Secrets Manager; never committed to git | OWASP A02 | | SQL injection | Prisma parameterised queries --- no raw SQL strings in application code | OWASP A03 | | API rate limiting | Redis-backed rate limiter: 100 req/min per IP, 1000 req/min per authenticated workspace | OWASP A04 | | Audit logging | All write operations emit audit events to append-only audit_log table | SOC2 CC6 | ### 9.2 Privacy & Compliance Guest data handling is designed to comply with GDPR (for European guests), Kenya's Data Protection Act 2019, Nigeria's NDPR, and South Africa's POPIA: - **Right to erasure:** Deletion requests trigger a cascade workflow that anonymises guest PII across episodes, messages, and asset records while preserving aggregate analytics (no PII in analytics layer) - **Data minimisation:** Only fields explicitly required for the outreach and booking workflow are collected; open-ended custom fields are locked behind workspace admin approval - **Data residency option:** Workspace billing tier unlocks the ability to specify storage region (Cloudflare R2 supports Africa South / Johannesburg edge) - **Consent tracking:** Outreach sequences record the basis for processing (legitimate interest for initial contact) and flag sequences where unsubscribe has been received ### 9.3 Guest Portal Security The guest portal uses signed tokens rather than account-based authentication. This eliminates friction for guests while maintaining security: - Tokens are HMAC-SHA256 signed with a workspace-specific secret, expiring after 7 days - Token scope is granular: a booking token cannot be used to upload assets; each token encodes permitted actions - IP-based rate limiting on portal endpoints (10 requests/minute) prevents token enumeration - All portal activity is logged with IP, user-agent, and action type for host visibility --- ## 10. Background Job Architecture The BullMQ job queue (backed by Redis) handles all asynchronous workloads. Jobs are grouped into named queues with defined concurrency limits, retry policies, and priority tiers. | **Queue Name** | **Jobs** | **Concurrency** | **Retry Policy** | **Priority** | |----------------|---------|----------------|------------------|--------------| | outreach | SendOutreachEmail, SendWhatsAppMessage, TrackEmailOpen, ProcessInboundReply | 20 workers | 3 retries, exponential backoff (1s, 5s, 30s) | HIGH | | enrichment | FetchLinkedInData, FetchTwitterData, GenerateIcebreaker, CalculatePriorityScore | 5 workers | 2 retries, linear backoff (10s, 30s) | MEDIUM | | scheduling | SyncCalendarAvailability, CreateCalendarEvent, SendBookingConfirmation, BookingReminder | 10 workers | 5 retries, exponential backoff | HIGH | | assets | ProcessHeadshotUpload, TranscribeAudioIntro, ValidateAssetSubmission, SendAssetReminder | 8 workers | 2 retries, linear backoff | MEDIUM | | ai_generation | GenerateShowNotes, GenerateSocialPosts, CreateAudiogram, GenerateQuoteCards | 3 workers | 1 retry, 60s backoff | LOW | | analytics | ComputeDailySnapshot, UpdateGuestScore, GenerateFunnelReport, ExportWorkspaceReport | 2 workers | 1 retry, 120s backoff | LOW | ### 10.1 Workflow Orchestration Complex multi-step workflows that span multiple queues are orchestrated using the Saga pattern implemented in NestJS. For Phase 1, this is implemented as NestJS Sagas (event-driven state machines). In Phase 3+, this migrates to Temporal.io for workflows with guaranteed durability and time-travel debugging. > **Example Saga** --- Guest Onboarding: GuestCreated → [EnrichmentJob] → GuestEnriched → [OutreachJob] → EmailSent → [Watchdog] → (Opened | NoResponse) → [FollowUpJob | CompleteJob] --- ## 11. Deployment & Infrastructure ### 11.1 Production Infrastructure | **Component** | **Service** | **Sizing (Phase 1)** | **Monthly Cost Est. (USD)** | |--------------|-------------|---------------------|---------------------------| | Web/Portal Frontend | Vercel (Pro) | Edge network, auto-scaling | $20/month | | API Server | AWS ECS Fargate (ap-south-1 Mumbai + af-south-1 Cape Town) | 0.5 vCPU / 1GB RAM × 2 tasks | $45/month | | Background Workers | AWS ECS Fargate (separate task definition) | 0.25 vCPU / 512MB RAM × 3 tasks | $18/month | | Database | AWS RDS PostgreSQL 15 (db.t4g.micro) | 1 vCPU / 1GB RAM, 20GB gp3 | $15/month | | Redis | AWS ElastiCache Serverless | Pay-per-use, auto-scaling | $8/month | | Search | Meilisearch Cloud (Build plan) | 5GB index, 100K docs | $30/month | | Object Storage | Cloudflare R2 (Standard) | 10GB storage, zero egress | $2/month | | Email | Resend (Pro) | 50K emails/month | $20/month | | Calendar API | Nylas (Starter) | 500 active connections | $0 (free tier) | | **Total Phase 1 (~500 podcasts)** | --- | --- | **~$158/month** | ### 11.2 Regional Deployment Strategy To minimise latency for African users, the primary API region is AWS af-south-1 (Cape Town), with a secondary region in ap-south-1 (Mumbai) for East African users (Nairobi latency to Cape Town: ~25ms vs. Mumbai: ~40ms). The guest portal runs on Cloudflare Workers globally, giving <50ms TTFB to any African city. ### 11.3 Scaling Triggers | **Scale Point** | **Trigger Condition** | **Architecture Change** | **Infrastructure Change** | |-----------------|----------------------|------------------------|--------------------------| | Phase 1 (0-1K podcasts) | Launch | Modular monolith, single ECS task | RDS t4g.micro, ElastiCache Serverless | | Phase 2 (1K-5K podcasts) | P95 API latency > 500ms OR CPU > 70% sustained | Extract Workers into separate ECS service | RDS t4g.small, dedicated Redis cluster | | Phase 3 (5K-20K podcasts) | Email volume > 100K/day OR Worker queue depth > 1K | Extract Outreach Domain to microservice, migrate to Temporal.io for orchestration | RDS t4g.medium with read replica, ElastiCache cluster mode | | Phase 4 (20K+ podcasts) | Cross-domain query latency > 2s P95 | Full microservices split, NATS JetStream event bus | RDS r6g.large per service, dedicated Meilisearch cluster | --- ## 12. Implementation Roadmap The roadmap is structured into four phases, each delivering a shippable product increment. The MVP focuses purely on eliminating the biggest time drains identified in the problem statement --- repetitive email follow-ups and manual scheduling. ### Phase 1 --- MVP (Weeks 1--6): Guest CRM + Scheduling | **Week** | **Deliverable** | **Technical Milestone** | |----------|----------------|------------------------| | 1--2 | Monorepo setup, NestJS + Prisma scaffolding, Clerk auth, basic tRPC routing | Infrastructure foundation, developer environment, CI/CD pipeline | | 3--4 | Guest CRM: add/edit/search guests, kanban pipeline view, CSV import | Core data model, Meilisearch integration, tRPC guest router | | 5--6 | Basic scheduling: Nylas calendar integration, booking page (Cal.com embed), ICS emails | Nylas OAuth flow, booking state machine, BullMQ reminder jobs | ### Phase 2 --- Outreach Automation (Weeks 7--12) | **Week** | **Deliverable** | **Technical Milestone** | |----------|----------------|------------------------| | 7--8 | Email template builder (Tiptap), outreach sequence designer, Resend integration | React Email templates, sequence state machine, BullMQ outreach queue | | 9--10 | Email tracking (open/click pixels), reply detection, automatic follow-up cadence | Tracking pixel endpoint, inbound email parsing, sequence watchdog jobs | | 11--12 | AI enrichment pipeline, personalised icebreaker generation, priority scoring | NVIDIA NIM, DeepSeek, Moonshot integration, enrichment BullMQ queue, priority score model | ### Phase 3 --- Asset Collection + AI (Weeks 13--18) | **Week** | **Deliverable** | **Technical Milestone** | |----------|----------------|------------------------| | 13--14 | Guest upload portal, chunked file upload to R2, asset request templates | Presigned URL generation, resumable upload endpoint, portal auth tokens | | 15--16 | Automated asset validation (headshot quality, audio transcription, link verification) | Vision API, Whisper, Puppeteer validation pipeline | | 17--18 | Post-recording AI pipeline: show notes, social posts, audiogram generation | Whisper transcription, GPT-4 generation, FFmpeg audiogram worker | ### Phase 4 --- Mobile + Analytics (Weeks 19--24) | **Week** | **Deliverable** | **Technical Milestone** | |----------|----------------|------------------------| | 19--20 | React Native app: guest list, status updates, push notifications, offline queue | Expo Router, WatermelonDB sync, Expo Notifications deep linking | | 21--22 | Analytics dashboard: funnel metrics, time-to-book, outreach conversion rates | Denormalised analytics tables, daily snapshot jobs, Recharts dashboards | | 23--24 | WhatsApp Business API integration, multi-channel outreach, unified inbox | WhatsApp webhook, channel abstraction layer, inbox aggregator | --- ## 13. Success Metrics & KPIs The core promise is reclaiming 20--30% of a podcaster's time. The following technical and product KPIs measure progress toward this goal. ### 13.1 Product KPIs | **Metric** | **Baseline (Manual)** | **Target (MicProtocol)** | **Measurement Method** | |-----------|----------------------|----------------------|----------------------| | Time to first outreach | 45-90 minutes (research + email) | < 5 minutes (AI-assisted) | Track from guest_created to first_email_sent timestamps | | Outreach reply rate | 15-20% (generic email) | 35-45% (AI-personalised) | outreach_messages: replied_count / sent_count | | Time from reply to booking | 2-3 days (back-and-forth) | < 4 hours (self-serve scheduling) | Booking created_at minus first positive reply timestamp | | Asset collection completion | 60% by recording day (manual) | 95%+ with automated reminders | asset_submissions: completed / required, sampled 24h before episode | | Guest no-show rate | 8-12% (minimal reminders) | < 2% (multi-channel reminders) | Bookings with recording_started = false / total bookings | | Host time saved per episode | Baseline TBD by cohort survey | ≥ 2 hours per episode target | In-app time tracking + periodic host survey | ### 13.2 Technical SLOs | **Service** | **SLO** | **Measurement** | **Alert Threshold** | |-------------|---------|----------------|-------------------| | API (p95 latency) | < 200ms for read queries | Datadog APM | Alert at > 500ms for 5 minutes | | API (p95 latency) | < 1,000ms for write/AI queries | Datadog APM | Alert at > 2,000ms for 5 minutes | | Guest portal TTFB | < 100ms globally | Cloudflare Analytics | Alert at > 300ms for 10 minutes | | Outreach email delivery | > 99% delivery rate | Resend webhook events | Alert if bounce rate > 3% in 1 hour | | Job queue depth | < 100 pending jobs per queue | BullMQ metrics + Redis | Alert at > 500 pending for 15 minutes | | Uptime | 99.9% monthly | Uptime Robot + Datadog | PagerDuty alert on 3 consecutive failures | --- ## 14. Open Architecture Decisions The following decisions require further input before finalisation. They are documented here to ensure they are addressed explicitly, not deferred indefinitely. | **Decision** | **Options** | **Recommendation** | **Owner** | |-------------|------------|-------------------|-----------| | Multi-tenancy model | (A) Shared database with RLS (current design) vs (B) Database-per-workspace for premium tier | Start with option A; design schema to support option B migration for Enterprise tier customers | Lead Engineer | | WhatsApp provider | (A) Twilio Conversations API vs (B) 360dialog (Africa-specialist, cheaper rates in KES/NGN) | Evaluate 360dialog pricing for KE/NG markets; default to Twilio for initial implementation | Product + Engineering | | Mobile money integration | (A) Flutterwave only vs (B) Flutterwave + direct M-Pesa Daraja API for Kenyan market | Phase 1: Flutterwave (simpler). Phase 2: Direct Daraja for Kenya to reduce fees by ~1.2% | Product | | Podcast RSS ingestion | (A) Manual podcast setup vs (B) Auto-import existing episodes and guests from RSS feed | Phase 2 feature: RSS feed import saves 30+ minutes for podcasters with existing shows | Engineering | | AI model hosting | (A) NVIDIA NIM, DeepSeek, Moonshot (current) vs (B) Self-hosted Llama 3 on AWS for data residency compliance | NVIDIA NIM, DeepSeek, Moonshot for Phase 1-3; evaluate self-hosted when ARR > $500K for cost and compliance reasons | CTO | --- ## 15. Conclusion MicProtocol's architecture is designed to deliver the 20--30% time savings promise not through feature accumulation, but through ruthless elimination of the specific friction points that waste podcaster time: the 3-email back-and-forth to book a call, the manual asset chasing 48 hours before recording, the generic outreach that gets ignored. The modular monolith approach ensures the team can move fast in Phase 1 while maintaining a clear, documented migration path to microservices as scale demands it. Every architectural decision is reversible without a rewrite. The African-first design decisions --- WhatsApp as a first-class channel, mobile money payment options, edge deployment for low-latency access across the continent, and offline-capable mobile app --- are not afterthoughts. They are architectural constraints baked into the foundation, because retrofitting African market requirements into a system designed for the US market is far more expensive than building them in from day one. > The technology is ready. The African podcasting ecosystem is growing at 40%+ year-over-year. The bottleneck is not recording quality or distribution --- it is the invisible administrative tax that limits how many guests a podcaster can engage. MicProtocol removes that tax.