# 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](./getting-started.md) → [Architecture](./architecture.md) |
| Operator running the stack | [Self-Hosted Stack](./self-hosted-stack.md) → [Operations Runbook](./operations-runbook.md) |
| Frontend / mobile developer | [API Reference](./api-reference.md) → [Architecture](./architecture.md) |
| Backend / integrations engineer | [Architecture](./architecture.md) → [Webhooks](./webhooks.md) → [Third-Party & Self-Hosted Integrations](./third-party-integrations.md) |
| Security reviewer | [Security & Compliance](./security.md) → [Webhooks](./webhooks.md) |
| ML / CLIP engineer | [CLIP Scoring Engine](./clip-scoring.md) |
| Recording / media engineer | [Recording Infrastructure](./recording-infrastructure.md) |
| QA / synthetic-agent author | [Synthetic Agents Testing](#synthetic-agents-testing) below |
| Product / exec | [Design Blueprint](./design.md) |

## Documentation Map

### Foundations

- [Getting Started](./getting-started.md) — prerequisites, full local setup, first-run checklist.
- [Architecture](./architecture.md) — modular monolith, bounded contexts, tech stack rationale, system diagram.
- [Design Blueprint](./design.md) — executive-level technical design, DDD, African-market context, roadmap.
- [Database Schema](./database-schema.md) — ERD, key constraints, index strategy.
- [Domain Workflows](./workflows.md) — guest state machine, asset collection, outreach cadence, production pipeline.
- [Subdomain Routing](./subdomains.md) — 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](../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](../apps/admin/README.md) |
| `@micprotocol/mobile` | Expo React Native app | `apps/mobile` | [apps/mobile/README.md](../apps/mobile/README.md), [apps/mobile/FEATURES.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](./clip-scoring.md) |
| `mic-realtime` (Erlang/OTP) | Chat fanout, presence, live domain events | [mic-realtime](#mic-realtime-service) below |

### Integrations

- [Self-Hosted Stack](./self-hosted-stack.md) — 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](./third-party-integrations.md) — per-integration purpose, ports, API clients, webhook endpoints, security.
- [Webhooks](./webhooks.md) — full HTTP reference for every webhook MicProtocol receives, including auth, idempotency, and side effects.
- [Formbricks Runbook](./formbricks-runbook.md) — deep-dive operational runbook for the Formbricks v4 stack.

### Subsystems

- [CLIP Scoring Engine](./clip-scoring.md) — three-axis scoring, fusion, distributed locking, cost analysis, troubleshooting.
- [Recording Infrastructure](./recording-infrastructure.md) — local-first double-ender, Green Room diagnostics, edge post-processing.

### Operations

- [Deployment & Scaling](./deployment.md) — environment strategy, scaling triggers, Dockerfiles, CI/CD.
- [Operations Runbook](./operations-runbook.md) — day-to-day ops, monitoring, incident response, disaster recovery.
- [Security & Compliance](./security.md) — auth, RLS, secrets, GDPR/POPIA/NDPR, audit logging.
- [API Reference](./api-reference.md) — REST + tRPC endpoint catalog by domain.
- [Verified Guest Network](./network.md) — 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`](../README.md)
- Agent notes: [`/AGENTS.md`](../AGENTS.md)
- Workspace config: [`/pnpm-workspace.yaml`](../pnpm-workspace.yaml)
- Turbo pipeline: [`/turbo.json`](../turbo.json)
- Full stack Docker Compose: [`/docker-compose.yml`](../docker-compose.yml)
- Coolify override: [`/docker-compose.coolify.yml`](../docker-compose.coolify.yml)
- Podman override (synthetic agents): [`/scripts/synthetic-agents/podman-compose.yml`](../scripts/synthetic-agents/podman-compose.yml)
- Environment template: [`/.env.example`](../.env.example)
- Coolify env template: [`/.env.example.coolify`](../.env.example.coolify)