docs/INDEX.md

MicProtocol Documentation

Welcome to MicProtocol — a domain-driven podcast guest management platform with a fully self-hostable integration stack.

This index is the entry point for every doc in this repository. Read top-to-bottom for newcomers; jump to a section when you know what you need.

Audience Map

You are…	Start here
New engineer onboarding	Getting Started → Architecture
Operator running the stack	Self-Hosted Stack → Operations Runbook
Frontend / mobile developer	API Reference → Architecture
Backend / integrations engineer	Architecture → Webhooks → Third-Party & Self-Hosted Integrations
Security reviewer	Security & Compliance → Webhooks
ML / CLIP engineer	CLIP Scoring Engine
Recording / media engineer	Recording Infrastructure
QA / synthetic-agent author	Synthetic Agents Testing below
Product / exec	Design Blueprint

Documentation Map

Foundations

• Getting Started — prerequisites, full local setup, first-run checklist.
• Architecture — modular monolith, bounded contexts, tech stack rationale, system diagram.
• Design Blueprint — executive-level technical design, DDD, African-market context, roadmap.
• Database Schema — ERD, key constraints, index strategy.
• Domain Workflows — guest state machine, asset collection, outreach cadence, production pipeline.
• Subdomain Routing — every workspace gets <slug>.micprotocol.io (sentry-style); DNS, TLS, local dev, reserved list.

Applications

App	Description	Code	App README
@micprotocol/api	NestJS backend (tRPC + REST + Socket.io)	apps/api	apps/api/README.md
@micprotocol/web	Next.js 14 host dashboard + guest portal	apps/web	(in repo)
@micprotocol/admin	Next.js platform-admin app	apps/admin	apps/admin/README.md
@micprotocol/mobile	Expo React Native app	apps/mobile	apps/mobile/README.md, apps/mobile/FEATURES.md

Packages

Package	Purpose
@micprotocol/shared-types	Domain enums and Zod schemas consumed by API, Web, Mobile, Admin
@micprotocol/ui	Cross-platform React UI primitives (Web + Mobile)
@micprotocol/tsconfig	Shared TypeScript configs (base, nextjs, nestjs)
@micprotocol/eslint-config	Shared ESLint config

Services

Service	Description	Doc
clip-scorer (Python)	Multimodal CLIP/audio/transcript scoring engine	clip-scoring.md
mic-realtime (Erlang/OTP)	Chat fanout, presence, live domain events	mic-realtime below

Integrations

• Self-Hosted Stack — unified ops guide for the entire self-hosted fleet (Postgres, Redis, MinIO, Cal.com, Formbricks, Documenso, Chatwoot, Listmonk, Umami, LiveKit, Mailhog).
• Third-Party & Self-Hosted Integrations — per-integration purpose, ports, API clients, webhook endpoints, security.
• Webhooks — full HTTP reference for every webhook MicProtocol receives, including auth, idempotency, and side effects.
• Formbricks Runbook — deep-dive operational runbook for the Formbricks v4 stack.

Subsystems

• CLIP Scoring Engine — three-axis scoring, fusion, distributed locking, cost analysis, troubleshooting.
• Recording Infrastructure — local-first double-ender, Green Room diagnostics, edge post-processing.

Operations

• Deployment & Scaling — environment strategy, scaling triggers, Dockerfiles, CI/CD.
• Operations Runbook — day-to-day ops, monitoring, incident response, disaster recovery.
• Security & Compliance — auth, RLS, secrets, GDPR/POPIA/NDPR, audit logging.
• API Reference — REST + tRPC endpoint catalog by domain.
• Verified Guest Network — two-sided marketplace, reputation engine, search, booking requests. (See also apps/api/src/network/README.md.)

Synthetic Agents Testing

The repo ships an end-to-end synthetic agent framework that simulates real users across five workspaces to find auth, isolation, validation, and privilege bugs.

• Code: scripts/synthetic-agents/
• Manifest: scripts/synthetic-agents/agents-manifest.json (5 workspace agents + 1 admin agent)
• Scenarios: 8 scenario modules in scripts/synthetic-agents/scenarios/:
  1. Workspace lifecycle (workspace-lifecycle.ts)
  2. Podcast operations (podcast-operations.ts)
  3. Guest pipeline (guest-pipeline.ts)
  4. Outreach sequences (outreach-sequences.ts)
  5. Booking & recording (booking-recording.ts)
  6. Verified network (verified-network.ts)
  7. Admin operations (admin-operations.ts)
  8. Cross-workspace isolation (cross-workspace.ts)
• Reporter: scripts/synthetic-agents/lib/reporter.ts (pattern-matches known weakness categories)
• Run: pnpm agents:run (full pipeline) or pnpm agents:orchestrator (API-only)
• Output: scripts/synthetic-agents/test-report.txt, scripts/synthetic-agents/weaknesses.json

Conventions

• File an issue or PR against docs/* for documentation changes.
• Mermaid diagrams (mermaid) render natively in GitHub, GitLab, and most static-site generators.
• Code references use path:line so they're clickable in IDEs and GitHub.
• "Self-hosted" refers to any service the docker-compose fleet runs; "third-party" refers to externally-hosted APIs the API code calls (Clerk, Resend, Cloudflare R2, NVIDIA NIM, DeepSeek, Moonshot, Stripe, Paystack, M-Pesa, Africa's Talking, Twilio, Google/Outlook calendars).

Repo Entry Points

• Top-level README: /README.md
• Agent notes: /AGENTS.md
• Workspace config: /pnpm-workspace.yaml
• Turbo pipeline: /turbo.json
• Full stack Docker Compose: /docker-compose.yml
• Coolify override: /docker-compose.coolify.yml
• Podman override (synthetic agents): /scripts/synthetic-agents/podman-compose.yml
• Environment template: /.env.example
• Coolify env template: /.env.example.coolify