MicProtocol / docs /design.md
Benaah's picture
Upload folder using huggingface_hub
b17baae verified
|
Raw History Blame Contribute Delete
38.8 kB

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.

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

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