Spaces:
Running
Running
| # 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) | |