How traffic flows from any capture client through the Busymate backend to your dashboard — the whole architecture in one page, with links to each component's internals.
Busymate has one job: capture HTTPS traffic from wherever it happens, and show it to you live. Everything below serves that flow.
The data flow
A capture client records request/response pairs and writes them to the backend; the backend fans every new row out over Realtime; the dashboard (or any subscriber) renders them the instant they land.
- A capture client records a request/response pair. The iOS app (VPN tunnel or PAC mode), the proxy-server (a Charles-style MITM for browsers/backends), and
bmc(already-decrypted Chrome DevTools traffic) are the three sources. - The client writes the entry to the backend — iOS and the proxy write directly to the
entriestable under their device credential;bmcposts through an ingest endpoint. Row-level security guarantees a client can only write its own rows. - The backend stores it in the partitioned
entriestable and a database trigger broadcasts the new row over Realtime to the entry's workspace channel. - The dashboard (and any other subscriber) is listening on that channel and renders the entry live — no polling, no gap.
One token, three ways in
Whether you read over REST, subscribe over Realtime, or call the MCP server, you present the same OAuth 2.1 access token. There's no separate API key per service. The token carries your identity and role, and every surface enforces row-level security plus capabilities server-side — so a request only ever returns or changes what your role allows. See Roles & permissions.
This single-token model is why the developer surface stays small: one credential, and the database does the access control for every path.
Where it runs — VPS + Cloud Pro
Busymate is split across two places:
- Supabase Cloud Pro (
api.busymate.net, a CNAME to the project) is the backend: Postgres (the source-of-truth schema), row-level security, Realtime, Auth, and the Edge Functions — including the MCP server and BusyBro. Capture clients read and write here; integrators reach it over REST/Realtime/MCP. - A single VPS hosts the pieces Busymate runs itself: the dashboard, the proxy-server, the docs + status sites, and nginx (with TLS). The proxy's per-device port pool and the CA cert distribution live here too.
The dashboard reads and writes the backend like any other client; the VPS is not in the data path between a capture client and the database — clients talk to api.busymate.net directly.
Component internals
Each component documents its own internals:
- How HTTPS decryption works — the Root CA, on-the-fly leaf certs, and iOS trust.
- iOS connection modes — VPN tunnel vs. PAC mode.
- Per-device attribution — how a request reaches the right device's feed.
- BusymateHelper internals — the iOS capture engine.
- Web proxy internals — Postgres ingest, Realtime control, the source-IP gate.
- CDP connector internals — how
bmccaptures Chrome traffic. - Status board internals — the standalone health board.
- BusyBro internals — the shared assistant brain.
Building an integration rather than reading internals? Start at the Reference — REST, Realtime, and MCP, all behind the one OAuth token.