Product and architecture documentation — the source of truth for what we're building. One topic per file.

• overview.md — product vision, goals, scope, and design principles
• roadmap.md — the phased build plan, tenancy model, and pending decisions
• engine.md — the engagement engine: events, workflows, segments, scheduled sends — the stack (subscriber actors on Durable Objects, Cloudflare Workflows, Tinybird) and how it feels (real apps with and without buzzkit); phases E1 Events through E8 iOS SDK built, E9 Workflows III in build, E10 Experiments designed; webhooks.md is the delivery engine, experiments.md the experimentation design
• architecture.md — runtime, API layers, APNs egress findings, testing, secrets
• configuration.md — every variable, secret and binding, what it is for, and what a self-hoster actually needs
• authentication.md — credentials, scopes, workspace addressing, isolation invariants
• admin.md — spec: user.admin, full invisible access to every workspace for support (changes show to the workspace as "BuzzKit Support"), the /v1/admin/* routes and the dashboard's admin section
• data-model.md — schema conventions and tables per phase
• design.md — the design system: tokens, components, motion, writing, the dashboard conventions (served at /design.md)
• dashboard.md — apps/web: auth architecture, route map, the onboarding flow, and the dashboard phase plan
• marketing.md — apps/marketing: the buzzkit.dev site, its structure, and the agent surface (llms.txt, markdown twins, well-known catalogs) that must stay in sync with copy changes
• buzz.md — Buzz, the agent notification app built on buzzkit: apps/ping (the API at ping.buzzkit.dev), the iOS app, the one-Live-Activity merge, the pairing credentials and the schema-versioning rules
• api/conventions.md — envelope, ids, verbs, lists, errors, idempotency, headers — the contract every endpoint follows
• api/ — one file per API resource: health, workspaces, tenants, keys, credentials, secrets, audit, webhooks, sources, events, segments, workflows, subscribers, imports, topics, messages, widgets, stats, client