Threadline — A Real-Time Collaboration Platform

Threadline is a room-centered collaboration workspace for engineering teams. A room is both a live session (video, audio, screen share, whiteboard, chat, shared editor) and a durable record of what happened in it — nothing is thrown away when the call ends. The whole system is three independently deployable services, each with a single job, none of them trusting the others' enforcement — that split, and what it costs and buys, is the actual subject of this repository.

• Overview
• Why Threadline exists
• Live deployment
• What's included
• Technology stack
• How the three services fit together
• Trust model
• Onboarding and workspace roles
• Interface sound
• Email delivery
• Engineering principles
• Performance and scaling characteristics
• Real incidents found operating this
• Testing and quality gates
• Observability
• What the interface looks like
• Project structure
• Running it locally
• Environment variables
• Commands
• Deploying it yourself
• FAQ
• Documentation index
• License

Threadline provides a single, unified workspace for a live call and its durable record, with three independent services each owning exactly one responsibility. The system is designed to demonstrate how to structure a realtime product across a serverless web tier, a serverless API tier, and a genuinely stateful coordination tier, with independent authorization checks at every boundary rather than a single shared trust domain.

• What a room is: a live WebRTC call (video, audio, screen share) plus a shared whiteboard, shared notes, a shared code editor, direct peer-to-peer file transfer, and chat — all synced in real time across every connected participant.
• What persists: chat messages, document edits, whiteboard updates, and who joined/left are written into a durable, permission-filtered timeline you can revisit after the call ends. Live-only signals (cursor position, WebRTC offers/answers/ICE candidates, individual whiteboard strokes) are deliberately never persisted — they're too high-frequency to be a meaningful record.
• What it's built to demonstrate: a production-quality realtime collaboration app split across three independent, mostly-serverless runtimes, each owning exactly one responsibility, with independent authorization checks at every boundary rather than a single shared trust domain.
• Three services, three jobs:
  • apps/web — Next.js UI and the browser-side WebRTC mesh, deployed to Vercel.
  • apps/api — Express API owning identity, attribute-based access control, rooms, calendar, and the durable event record, backed by MongoDB Atlas.
  • apps/realtime — one Cloudflare Durable Object per room, owning live presence and WebRTC signaling relay.
• Who this is for: engineers evaluating how to structure a realtime product across a serverless web tier, a serverless API tier, and a genuinely stateful coordination tier, and wanting to see the actual trade-offs (not just the happy path) written down.

• The product problem it solves: most teams run a live call in one tool (a video conferencing app) and keep the record of what happened in a completely different one (a wiki page, a chat thread, a shared doc someone remembers to update afterward). Threadline treats the room itself as the unit that owns both — the live session and its durable history are the same object, not two things a human has to reconcile by hand.
• The engineering problem it's built to explore: a single conventional server handles "many stateless requests" well and "one coordinator per active room, globally consistent, cheap when idle" poorly. Threadline exists to work through that specific mismatch honestly — one plane (apps/realtime) is intentionally not stateless, and the rest of the system is designed around that fact rather than around pretending everything can be a normal REST service.
• Why it's a real, running deployment rather than a diagram: every claim in this repository's documentation — the trust boundaries, the failure modes, the incidents — is backed by a system you can actually open, register an account on, and break in the same ways it was broken during development. Real incidents found operating this and docs/operations.md exist because this was operated, not just designed.
• What it deliberately does not try to be: a broadcast/streaming platform (no SFU, no one-to-many fan-out — see Architectural trade-offs and current limitations), a general-purpose project management tool, or a fully managed multi-tenant SaaS with billing. It is scoped to small, focused working sessions for a single organization at a time.

• Web app: threadline-rtc.vercel.app — create a real account and try it.
• Swagger UI: threadline-app-api.vercel.app/api-docs — interactive, try-it-out against the live API.
• ReDoc: threadline-app-api.vercel.app/api-docs/redoc — three-pane reference.
• Realtime: threadline-realtime.threadline-dn.workers.dev — the Cloudflare Worker that hosts RoomDurableObject. There's nothing to browse here: it's a WebSocket/signaling endpoint the web app connects to with a signed room ticket, not a page meant to be opened directly.
• What's actually running there: the same code in this repository, deployed with apps/web and apps/api both on Vercel (as two separate projects) and apps/realtime on Cloudflare Workers — the exact topology diagrammed in Browser-facing topology and detailed in docs/deployment.md.

• Web app (apps/web):
  • Registration, login, and password recovery. Signing up no longer locks an account into any one workspace — see Onboarding and workspace roles. There is no email-verification flow, deliberately — see Email delivery.
  • A full-screen onboarding step, shown whenever an account has zero workspaces, offering two card-based paths: create a new workspace (becoming its owner) or join an existing one via invite code.
  • A real workspace switcher in the sidebar — accounts can belong to more than one workspace, switch between them from a dropdown, and the last-used workspace is remembered (localStorage) and restored on the next visit.
  • Organization dashboard: recent rooms, recent activity, a room-creation modal.
  • A dedicated rooms directory listing every room the caller can see.
  • A live room view with five panels — chat, shared notes, a drawable whiteboard, direct peer-to-peer file transfer, and a durable event timeline — plus a separate shared code editor mode and camera/mic/screen-share controls.
  • Keyboard shortcuts for the call controls — M microphone, V camera, S screen share — ignored while typing so they can't fire from a chat message, and listed behind a keyboard button in the call bar rather than left for people to discover by accident. Leaving a call deliberately has no shortcut. Hidden entirely on touch devices, where there is no key to press.
  • The landing page and the authentication pages respect an existing session: signed in, the calls to action open the workspace instead of offering sign-up, and /login, /register, /forgot-password, and /reset-password redirect rather than inviting a second sign-in over a live session.
  • An organization-wide calendar for scheduling sessions, and an org-wide activity feed aggregating durable events across every visible room.
  • Organization membership management: a shareable, regenerable invite code (owner/admin-controlled, optionally delegable to members), per-member role changes (owner/admin/member) with a last-admin self-demotion guard, and per-room membership management (granting explicit access to restricted rooms).
  • Loading skeletons across every list-driven page (rooms, members, activity, calendar, sessions/tokens/clients) so a still-loading list is never mistaken for a genuinely empty one.
  • A dedicated profile page reached from the topbar avatar: identity summary, editable display name and username, and every workspace the account belongs to with its role. A rename updates the workspace chrome immediately rather than waiting for a reload.
  • Account settings: appearance/theme, interface sounds, active browser sessions (list and revoke), personal access tokens (create, scope, revoke), and first-party OIDC clients.
  • Interface sound feedback for joining, leaving, muting, camera, screen share, chat, and peer presence — synthesised with the Web Audio API rather than shipped as audio files, and switchable off in settings. See Interface sound.
  • A custom, branded 404 page rather than a framework default.
• API (apps/api):
  • Identity and session management, with three independent authentication surfaces: browser session cookies, personal access tokens, and first-party OIDC.
  • Organizations, rooms, room membership, and a calendar resource, all protected by attribute-based access control re-derived on every request.
  • Self-service workspace creation and invite-code-based joining (POST /v1/orgs, POST /v1/join), decoupled from registration — see Onboarding and workspace roles.
  • Personal access token issuance, scoping, listing, and revocation.
  • A first-party OpenID Connect provider implementing Authorization Code + PKCE — no implicit grant, no password grant, no public third-party client registration.
  • An internal ingest endpoint that accepts durable events forwarded by the Durable Object, independently re-checking authorization for the event's acting user rather than trusting the forwarding secret alone.
  • Error and performance monitoring via Sentry, inert by default (no-ops with no SENTRY_DSN configured) — see Observability.
  • Fully documented as an OpenAPI 3.1 specification, served live at /api-docs (Swagger UI) and /api-docs/redoc (ReDoc).
• Realtime (apps/realtime):
  • One Cloudflare Durable Object per room, created on demand and addressed deterministically from the room's ID.
  • Presence tracking and WebRTC signaling relay (SDP offers/answers, ICE candidates) over hibernatable WebSockets, so an idle-but-connected room costs no ongoing compute.
  • SQLite-backed storage for the retry queue behind the durable-event hand-off.
  • Retried, alarm-scheduled delivery of durable events back to the API — a failed hand-off doesn't drop the event, it queues and tries again.
• WebRTC client (apps/web/lib/peer-mesh.ts):
  • A hand-rolled full-mesh client — one RTCPeerConnection and one data channel per remote participant, with no third-party WebRTC SDK.
  • Camera and microphone streaming, screen sharing, and peer-to-peer chunked file transfer over the data channel.
  • No media server anywhere in the stack — once signaling completes, audio/video/screen/file bytes never touch a Threadline-operated server again.

graph LR
    Browser["Browser"] -->|"session cookie / PAT"| Web["apps/web<br/>Next.js on Vercel"]
    Web --> API["apps/api<br/>Express"]
    Browser -->|"signed room ticket<br/>WebSocket"| RT["apps/realtime<br/>Cloudflare Durable Objects"]
    API --> DB[("MongoDB Atlas")]
    API -.->|"optional: rate-limit windows,<br/>session touches — falls back to Mongo"| Redis[("Redis")]
    RT -->|"durable event webhook"| API
    Browser <-.->|"WebRTC: audio, video,<br/>screen share, files"| Browser

    style DB fill:#123524,stroke:#52e0a2,color:#fff
    style Redis fill:#2b2140,stroke:#8a63ff,color:#fff

• The browser talks to apps/web over HTTPS with a session cookie or PAT.
• apps/web proxies the API through a same-origin rewrite, so the session cookie stays first-party even though the API is a separate Vercel project.
• The browser opens a WebSocket directly to the Cloudflare Worker, authenticated by a short-lived, single-purpose signed ticket — not the session cookie.
• The Durable Object never talks to MongoDB. It only hands events to the API over an authenticated webhook, retrying if that fails.
• Redis is the only dashed arrow for a reason: it holds nothing that cannot be recomputed. Every operation behind it falls back to MongoDB when it is unset, unreachable, or slow, and apps/realtime has no Redis dependency at all.
• WebRTC media (audio/video/screen/files) flows peer-to-peer once signaling completes — never through a server.
• Full breakdown: ARCHITECTURE.md and docs/architecture.md.

• No plane trusts another plane's enforcement — every one independently re-verifies who's allowed to do what, using its own credential, on every request.
• The Durable Object verifies its own signed room ticket (signature and room ID) before accepting a WebSocket upgrade.
• The API re-checks attribute-based access control on every request, including events forwarded by the Durable Object over its internal webhook — a valid shared ingest secret proves the request came from the trusted Worker, not that the acting user embedded in the event may actually write to that room.
• Session cookies, personal access tokens, and OIDC tokens are three genuinely different credential types with different lifetimes and capabilities — a PAT, even one scoped admin:*, is explicitly barred from session-only routes such as creating another PAT or listing browser sessions.
• Two secrets are shared across two different platforms (Vercel and Cloudflare) with nothing in the code enforcing they match: ROOM_TICKET_SECRET and the INTERNAL_INGEST_SECRET/PERSISTENCE_SECRET pair. Getting either wrong fails silently at runtime — every ticket rejected, or every durable event silently never persisted — not at deploy time.
• Full secrets inventory, with a diagram of exactly which secret crosses which boundary and what it authorizes: docs/security.md.

Registration does not create or join a workspace. A brand-new account has zero organizations until it explicitly does one of two things, both reachable from a full-screen onboarding step (mandatory when an account has no workspace, optional and reachable from the sidebar switcher afterward, for adding another one):

• Create a workspace (POST /v1/orgs) — the caller becomes its owner, and a fresh, unique, regenerable join code is generated for it.
• Join a workspace (POST /v1/join) — redeems another workspace's join code and creates a member membership. Rate limited the same as a password check (10/15min/IP), since it's a caller-supplied secret checked against every organization in the system.

Three roles exist per membership — owner, admin, member — enforced the same way as every other permission in the system: re-derived from the database on every request, never cached or inferred from an ID.

• Only an owner may grant admin. An admin (or a member with the delegated canManageMembers attribute) can manage members and change roles, but cannot escalate anyone to admin.
• An admin can self-demote to member only if another admin already exists in the organization; otherwise the API rejects it (400 last_admin) rather than leaving the workspace with no one able to manage it. This guard only applies to a caller changing their own role — an owner-directed demotion of someone else is exempt, since the owner remains a fallback administrator regardless.
• The join code is a genuine secret, never included in any general-purpose response (GET /v1/auth/me, GET /v1/orgs) — only the dedicated, permission-gated GET /v1/orgs/:orgId/invite endpoint returns it. Viewing or regenerating it is available to owners/admins always, and to plain members only when the organization has opted in via allowMemberInvites.
• A non-member gets an identical 403 whether the organization they're asking about is real or doesn't exist — the invite endpoints deliberately never leak organization existence through a status-code difference.

Room and call access was already, and remains, gated on organization membership: effectiveRoomRole() returns nothing for a caller with no membership row at all, so an account with zero workspaces has no route into any room regardless of how it got there.

Full design and endpoint-by-endpoint detail: docs/api.md and docs/glossary.md.

Short cues mark the events you can't see happen: joining and leaving a room, muting, camera on/off, starting and stopping a screen share, sending and receiving a message, and someone else arriving or leaving.

They are synthesised at runtime through the Web Audio API, not shipped as audio files. A dozen cues as WAVs would be a few hundred KB of binaries carrying their own licences, and each would need a network round trip before the first mute click could be heard. As synthesis the whole palette is a table of frequencies in apps/web/lib/sound.ts, it costs nothing until something happens, and a cue's character is tuned by editing a number instead of re-cutting a file.

The palette is one interval set (D major pentatonic) so cues sound related rather than arbitrary, and every cue is paired — whatever rises to turn something on falls to turn it back off. Levels were not guessed: the module was rendered through an OfflineAudioContext and measured.

Repeats of the same cue inside 90 ms are dropped, so a burst of arrivals does not machine-gun. Off is one click in Settings → Appearance → Interface sounds, and the preference persists per device.

Threadline has no built-in transactional email provider. Account recovery does not need one; everything else that would have sent mail is gone.

Anything that would send mail is handed to the webhook named in AUTH_DELIVERY_WEBHOOK — a service you supply. When that variable is unset, the delivery callback is never constructed and no mail leaves the system.

Two consequences follow, both stated plainly rather than discovered later:

• There is no email-verification flow. It previously existed and silently did nothing: the request endpoint wrote a token and answered 202 Accepted for mail that was never sent. Reporting success for work not done is worse than not offering the feature, so both endpoints and every piece of "Verified / Unverified / Resend link" UI were removed. Credential.emailVerifiedAt and the OIDC email_verified claim remain, because the claim is part of the OIDC contract and reporting it as false is accurate.
• Password recovery does not depend on mail. Every account is issued eight single-use recovery codes at registration, shown once and stored only as hashes. POST /v1/auth/password-reset/redeem takes an email and one code, sets a new password, and revokes every session for the account. The link-based password-reset/request/confirm pair still exists for deployments that do configure a webhook, and still only completes there.

Recovery deliberately proves possession of a secret, not knowledge of account facts. publicUser hands a member's email, username, and display name to everyone else in their workspace, so a "confirm these details to reset" flow would let any colleague take over any account — including an owner's. A recovery code is ~59 bits of entropy that no one but the account holder has ever seen.

• Independent re-verification, not shared trust. Every plane re-derives authorization from scratch on every request rather than caching a decision or trusting what an upstream plane already claims to have checked.
• One Repository interface, two implementations. MemoryRepository backs local dev and the real HTTP-level test suite with zero database connection; MongoRepository backs production. Route handlers in apps/api/src/application.ts only ever call the interface — this is what lets createApp() boot identically on a test runner, Docker, Kubernetes, or Vercel. Rationale: ADR-0003.
• Attribute-based access control, computed fresh every time. Every permission decision is derived from the caller's organization role, explicitly delegated attributes, and — for rooms — the room's own visibility and classification, re-evaluated on every request rather than inferred from an ID or cached from a previous check.
• Fail closed on misconfiguration, at boot, not at request time. apps/api/src/index.ts refuses to start in production with an insecure or incomplete configuration — short secrets, non-HTTPS origins, a missing signing key — rather than starting with a silently weaker default. See Boot-time validation.
• Secrets are single-purpose and never reused across trust boundaries. The value that authorizes a WebSocket connection is not the value that authorizes a durable-event webhook call, which is not the value that signs an OIDC access token. A leak of one does not compromise what the others protect.
• No media server, by design. WebRTC media takes the shortest path available — peer-to-peer — rather than routing through infrastructure Threadline would have to run, secure, and pay for per minute of call time. The cost of that choice (mesh bandwidth scales with participant count) is written down, not hidden: ADR-0002.
• Explicit field whitelists over blacklists when serializing anything from a database driver. const { secretField, ...rest } = doc looks safe but silently includes whatever else the driver happened to attach to that object — the MongoDB driver mutates an inserted document by adding its own _id, which leaked into two responses this exact way before being replaced with an explicit publicOrganization() whitelist. The identical, still-unfixed pattern elsewhere in the codebase is tracked, not hidden: docs/roadmap.md.
• A unique index on a field added to an already-populated collection is a migration, not just a schema change. It needs a backfill pass before (or atomically with) rollout, or it can take the whole service down at boot — this one did, in production, for real. See the incident that taught this.
• Honesty over polish in the documentation itself. The incidents, known limitations, and roadmap gaps below are real and current, not a marketing summary — see Real incidents found operating this and docs/roadmap.md.

Concrete numbers, not marketing — what actually happens as usage grows, and where the real ceilings are.

This deployment has broken for real, more than once. Every incident — what broke, why, how it was found, how it was fixed — is written up in full in docs/operations.md. Twelve so far, briefly:

• A WebRTC negotiation bug where two participants could join the same room and simply never connect, because neither side happened to offer first.
• A Durable Object hibernation quirk where a participant who'd just disconnected kept appearing "present" to everyone else, indefinitely, because the departing socket still counted itself present in the same broadcast that announced its own departure.
• A rate limiter silently sharing one counter across four different endpoints, because of how Express rebases request paths inside route mounts — hammering /login measurably ate into /register's budget.
• Durable events (chat, joins, document edits) never persisting at all, because apps/realtime/wrangler.toml was missing its [vars] block entirely, so the persistence webhook URL was undefined and delivery was silently never attempted.
• A room-ticket signing mismatch between apps/api and apps/realtime, causing every WebSocket connection to be rejected with no visible error beyond "bad response from the server."
• A persistence-secret mismatch on the same webhook, after the URL itself was fixed — the two independently configured platform secrets simply didn't match.
• A production web app deployed with zero environment variables, meaning registration and login were completely broken for every real user despite the build succeeding and the site returning 200.
• WEB_ORIGIN pointed at localhost:3000 in a production deployment, silently rejecting every real cross-origin request as a CSRF violation.
• OIDC_ISSUER set to a URL that included a path, which crashed the entire API at boot — every route, not just the OIDC ones — because parseOrigin() rejects any value that isn't a bare origin.
• A seeded first-party OIDC client whose redirect URI never updated when the web app's domain changed, breaking login through that specific flow until the seed logic was made self-healing.
• Deploying the workspace/role rework's new unique index on organizations' join codes crashed every API request in production, because ~22 pre-existing organizations had no joinCode at all and the index build failed on duplicate nulls — fixed with a one-off backfill, not a rollback.
• Deploying an unrelated feature branch that happened to be based on an older main silently reverted the live API to a previous, still-superseded registration schema for several minutes, because the deploy source was the wrong branch rather than the one actually intended.

• Every automated suite runs against the actual runtime it targets rather than a mock of it: apps/api's HTTP-level integration suite (supertest against a real createApp() and a real MemoryRepository, zero mocking of Express or the repository), apps/realtime's Durable Object suite (real hibernatable WebSocket handlers and SQLite storage inside an actual Workers runtime via @cloudflare/vitest-pool-workers), and a small apps/web layer covering the WebRTC mesh, the sound engine, and CSS-level layout guards run in real Chromium via Playwright (npm run test:browser, also gated in CI).
• apps/web still has no component or page-level test suite. What exists there is unit and layout coverage, not rendering coverage: no page is mounted, no fetch-driven state is asserted. Every UI bug found in this project — the WebRTC mesh initiator bug, the stale-presence-after-disconnect race, the whiteboard off-tab stroke loss — was found through live manual testing against the running app, including genuine two-independent-browser-context sessions (two separate cookie jars, two separately registered real users). This remains the largest testing gap in the repository, written down honestly rather than glossed over: docs/testing.md.
• Layout regressions are asserted numerically, not by screenshot. control-centering.spec.ts measures how far a control's contents sit from the centre of its own content box and fails past half a pixel — the check that would have caught the off-centre tab labels and icon buttons, and one verified to fail when the old CSS is restored rather than merely passing against the new.
• Documentation is verified mechanically, not by review alone. The TypeDoc build treats validation warnings as errors, so a {@link} to a symbol that no longer exists or a public signature referencing an unexported type fails CI rather than shipping as dead text. npm run docs:links separately checks all 482 relative markdown links and their anchors — including that a heading actually produces the anchor a link claims. External URLs are deliberately not fetched, so a third-party site being briefly down cannot turn a pull request red.
• Three gates run on every pull request, not one. The CI/CD pipeline (lint, typecheck, dependency audit, tests, build, container and Kubernetes validation), PR Hygiene (the title, every commit message, a non-empty description), and Documentation (TypeDoc built with strict validation, plus link checking).
• Container images are proven to run, not merely to build. The containers job starts the full Compose stack, waits for every healthcheck, and smoke-tests each service over HTTP — including the web tier's same-origin proxy actually reaching the API container. A build-only check answers "did this assemble?" when the question worth asking is "does this start?"; the difference was one latent defect that made npm run docker:up impossible while CI stayed green (operations.md).
• Three git hooks, tiered by cost. pre-commit is fast — lint-staged plus a guard for committed secrets, .env files, merge conflict markers, debugger, and focused tests. commit-msg validates the conventional-commit format with the same script CI uses, so local and remote enforcement cannot drift. pre-push runs typecheck and tests. All three are bypassable on purpose; a bypass belongs in the PR description.
• The full local check, mirroring what gates a merge in CI:

  make check    # or: npm run check

  make check runs every step even after one fails, then prints a summary — so "your formatting is wrong" never hides "your tests are broken".
• Full test-suite structure, exactly what's covered, and every known coverage gap: docs/testing.md.

Both apps/api (@sentry/node) and apps/web (@sentry/nextjs) are instrumented for error and performance monitoring, and both are fully inert with no configured DSN — every Sentry.* call safely no-ops, so nothing about running the app locally or in CI depends on having a Sentry account.

• apps/api: src/instrument.ts runs as the literal first import of src/index.ts, ahead of everything else, so Sentry can instrument what loads after it. The final Express error handler reports only its genuinely-unexpected branch — validation errors (z.ZodError) are expected user-input noise and are never sent.
• apps/web: standard App Router instrumentation (instrumentation.ts for server/edge, instrumentation-client.ts for the browser), plus next.config.ts wrapped with withSentryConfig for optional source-map upload (skipped, not failed, without an org/auth token — see Environment variables).
• Enable it by setting SENTRY_DSN (API) and NEXT_PUBLIC_SENTRY_DSN (web) as environment variables in each deployment target and redeploying — no code changes required.

All screenshots below are taken directly against the live deployment. The chat and whiteboard screenshots use two independently authenticated browser sessions connected to the same room at the same time — real, live two-person sync, not a mockup.

_{Landing page}

_{Workspace dashboard}

_{Rooms List Page}

_{Room - Before Joining the Call}

_{Room - During the Call}

_{Organization Calendar -- Scheduling Page}

_{Activity feed — durable events across every visible room}

_{Personal Profile Page}

_{Workspace Members List Page}

_{Account settings}

_{Login Page}

_{Register Page}

_{API Documentation}

_{API Documentation (ReDoc)}

Threadline/
├── apps/
│   ├── web/                  Next.js App Router UI (Vercel)
│   │   ├── app/               routes: landing, auth screens, /app/** workspace
│   │   ├── components/        React client components
│   │   ├── lib/                apiFetch() HTTP client, PeerMesh WebRTC client
│   │   └── public/            static assets
│   ├── api/                   Express REST API (Vercel / any Node 22 host)
│   │   ├── Dockerfile
│   │   └── src/
│   │       ├── domain.ts       entity types (User, Room, Session, PAT, ...)
│   │       ├── repository.ts   Repository interface + Memory/Mongo implementations
│   │       ├── cache.ts        Cache port + Memory/Redis implementations (optional, evictable)
│   │       ├── policy.ts       ABAC decision logic
│   │       ├── application.ts  createApp() factory, routes, middleware
│   │       ├── security.ts     hashing, tokens, cookies
│   │       ├── instrument.ts   Sentry.init(), imported first in src/index.ts
│   │       └── openapi.ts      OpenAPI 3.1 document
│   └── realtime/               Cloudflare Worker + Durable Object
│       ├── Dockerfile           local Wrangler emulation, not the Cloudflare deploy path
│       └── src/index.ts        RoomDurableObject
├── docs/                      Deep-dive documentation
│   ├── decisions/               Architecture Decision Records
│   ├── screenshots/             Curated UI screenshots used across the docs
│   └── api-reference/           Generated TypeDoc symbol reference (gitignored)
├── infra/
│   ├── docker/                  Fixtures consumed by apps/realtime/Dockerfile (dev-only secrets)
│   └── kubernetes/               Kustomize base + overlays
├── scripts/                   Repository tooling — bootstrap, check, doctor, clean, guards
│   └── lib/common.sh            Shared bash helpers
├── .devcontainer/             Dev container: full toolchain + a MongoDB sidecar
├── .husky/                    Git hooks — pre-commit, commit-msg, pre-push
├── .claude/skills/            Task-specific workflows for coding agents
├── .github/
│   ├── workflows/               CI: pipeline, PR hygiene, docs, labels, stale
│   ├── ISSUE_TEMPLATE/          Bug, feature, and documentation issue forms
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── CODEOWNERS               Security-sensitive paths get an explicit owner
├── compose.yaml               Local Docker Compose stack (web + API + realtime + MongoDB + Redis)
├── Makefile                   Task runner — `make help` lists everything
├── typedoc.json               Generated API reference configuration
├── AGENTS.md                  Conventions for coding agents (authoritative)
├── CLAUDE.md                  Claude Code specifics; defers to AGENTS.md
├── SECURITY.md                Private disclosure process, scope, safe harbor
└── ARCHITECTURE.md            Root-level architecture reference (this repo's single-file overview)

• Full monorepo layout, one level deeper, with what each file is responsible for: docs/architecture.md.

Prerequisites: Node.js 22 or newer, and npm (this is an npm-workspaces monorepo — one npm install at the root installs all three workspaces).

make setup    # checks your toolchain, installs, wires hooks, seeds env files
npm run dev

make setup is idempotent and never overwrites an existing env file. The manual equivalent is npm install plus copying apps/web/.env.example and apps/realtime/.dev.vars.example into place. If anything misbehaves, npm run doctor diagnoses the environment — Node version, dependency consistency, git hooks, env files, and whether the four ports are free — and prints the remedy for each finding.

Open http://localhost:3000. npm run dev starts all three services, wired to talk to each other correctly:

• The local Worker reads its dev secrets from apps/realtime/.dev.vars (gitignored).
• Without MONGODB_URI set, apps/api uses an in-memory repository — zero database setup needed to run locally, but every restart of the API process (including tsx watch restarts on save) clears it.
• Stop everything with Ctrl+C.
• Run one service alone: npm run dev:api:local, npm run dev:realtime:local, or npm run dev:web:local.
• Prefer containers? npm run docker:up starts web + API + a real local MongoDB + a local Redis + the local Durable Object runtime together, so state survives restarts. Full guide: docs/containers-and-kubernetes.md.

The three services need different configuration, summarized here — the full table with every variable, its purpose, and production requirements lives in docs/deployment.md.

• ROOM_TICKET_SECRET must be identical on apps/api and apps/realtime. PERSISTENCE_SECRET (Worker) must be identical to INTERNAL_INGEST_SECRET (API) — different names, same value. Nothing in the code enforces either match; getting one wrong is exactly what caused two of the real incidents above.
• Every Sentry variable is optional and additive — omitting all of them leaves both SDKs inert (no-op), never a startup or build failure. See Observability.
• Never put MongoDB, Redis, OIDC, room-ticket, email-delivery, or TURN credentials in NEXT_PUBLIC_* variables — those are shipped to every browser that loads the page.
• Local defaults exist for everything except MONGODB_URI, so local dev needs no secrets configured at all beyond copying .dev.vars.example. Production has no such fallback — see Boot-time validation.

make help prints every task grouped by purpose — the Makefile is a discoverable front door to the npm scripts above plus the multi-step workflows (make setup, make check, make ports, make ci).

• Before opening a PR: make check — the same chain CI runs, with every step executed even after a failure so one broken step doesn't hide another. Details: docs/testing.md.
• Contributing a change? Start with CONTRIBUTING.md.
• Working with a coding agent? AGENTS.md holds the conventions they follow.

• The API validates every mandatory production setting at boot — Atlas connection, HTTPS-only origins, a stable RSA signing key, separate room-ticket/ingest secrets, an authenticated email-delivery webhook. It refuses to boot half-configured.
• Generate the OIDC signing key once: npm run generate:oidc-key --workspace=@threadline/api. Rotating it invalidates every OIDC token issued under the old key, so it isn't done casually.
• apps/web and apps/api can both run on Vercel, as this project's own deployment does, or apps/api can run on any always-on Node 22 host (Render, Docker, Kubernetes) — the same createApp() boots identically either way.
• apps/realtime deploys to Cloudflare Workers with wrangler deploy; its two shared secrets are set with wrangler secret put and must match the corresponding API values exactly.
• Zero-cost preview path (free tiers of Vercel + MongoDB Atlas + Cloudflare, no domain purchase): see docs/deployment.md.
• Self-hosting the stateless web/API tier on Kubernetes instead of Vercel/Render, while Cloudflare remains the production owner of room Durable Objects: docs/containers-and-kubernetes.md.
• Exactly which URLs this project's own live deployment runs at, and how that maps onto the general deployment guide: docs/deployment.md.

Is this used by real teams, or is it a demo? It's a real, running deployment — not a multi-tenant SaaS with paying customers, but not a static demo either. Registering a real account on the live deployment creates a real workspace, backed by the same production database and the same code in this repository. "Production-ready" here means correctly designed and genuinely operated (real incidents, real trust boundaries, real test coverage where it exists), not "battle-tested at scale with a support team."

Why MongoDB instead of a relational database? The data model — users, rooms, memberships, a growing durable event timeline — is document-shaped, and every read is already scoped by a single indexed ID (organization, room, or user), not a cross-table join. The Repository interface (ADR-0003) means this choice isn't load-bearing either way — swapping the datastore touches one file, not the route handlers.

Why a first-party OIDC provider instead of Auth0, Clerk, or NextAuth? Partly to build the actual flow (Authorization Code + PKCE, JWKS, token rotation) rather than configure someone else's, and partly because a third-party auth platform is one more service in the exact trust model this repository is about being honest regarding — see Trust model.

Why Cloudflare Durable Objects instead of Redis/Ably/Pusher for presence? Those solve "many stateless servers agree on shared state" by adding a coordination service Threadline would have to run, operate, and pay for. A Durable Object gives one authoritative, in-memory instance per room natively, with no separate service and no consistency protocol to write by hand. ADR-0001 has the full tradeoff against that alternative.

That answer is unchanged by apps/api optionally using Redis for rate-limit counters (ADR-0009) — a counter has no owner to elect, which is the entire reason presence and a counter get different answers. apps/realtime has no Redis dependency and cannot have one: workerd has no Node TCP socket.

Can I run this without Vercel or Cloudflare? apps/web and apps/api can run anywhere Node 22 runs — Docker, Kubernetes, bare metal — see docs/containers-and-kubernetes.md. apps/realtime genuinely cannot: it's written against the Durable Objects API, which is Cloudflare-specific, and there's no portable equivalent without rewriting the presence/signaling layer against a different coordination primitive entirely.

What happens to an in-progress call if apps/api goes down? Nothing, live — chat, presence, and WebRTC signaling all keep working, since none of that path touches the API. New room creation, login, and durable-event history reads fail. Full breakdown: Failure behavior.

How much does this cost to run? The zero-cost public preview path runs on free tiers of Vercel, MongoDB Atlas, and Cloudflare Workers, no domain purchase — real limits apply (cold starts, free-tier caps), but genuinely $0. This project's own live deployment runs this way.

Why is there no component test suite for the frontend? There is some apps/web coverage — the WebRTC mesh, the sound engine, and CSS-level layout guards that run in real Chromium — but nothing that mounts a page or asserts fetch-driven state. That remains the largest testing gap in the repository, named rather than hidden: see Testing and quality gates for exactly what it covers and what catches bugs instead.

MIT. See LICENSE for details.