Cockpit · architecture

Architecture

How Cockpit is built, drawn from the repository alone: who and what it talks to, the areas the code is made of and what in them breaks the agreed boundaries, and where it runs.

commit d533189 commit dated 2026-10-12 19 areas 3 environments 9 workflows Test explorer → CI stability → Cycle time → Selection →

What changed

Since the commit the live report was drawn from, 8bc1abf (2026-10-12), to d533189 (2026-10-12). Both are drawn by this generator, so a change to the generator alone is not listed.

Nothing changed.

Context Open full size →

Who uses Cockpit and the outside services it depends on, as tools/architecture/description.yml declares them.

Cockpit Unified inbox and dashboards, one Worker per environment on Cloudflare serving the API, live updates and the app. production · staging People in a workspace browser, installed PWA, share sheet Guest demo sign-in, reset every night Admin and operator admin pages, backup and restore AI agents Claude.ai, Claude Code over MCP Google sign-in, Gmail API Microsoft Entra sign-in, Teams via Bot Framework Anthropic Claude API reads captured notes Cloudflare Workers AI embeddings, notes that repeat GitHub code, CI, deploys, report pages

Modules Open full size →

Every area of the web app, the API and the packages, each on the row below everything that imports it, and a box per connector the description file declares. Only the shortest chain of imports is drawn, each arrow labelled with the files that make it. The marks are shown and nothing fails on them.

Imports an area below An import back up the chain, closing a cycle, with its files; a tie where both halves are the same size Connector code living in the core: move it into the connector (3 files) A connector with no package of its own, or whose package is gone (1 of 3) A connector package importing beyond the SDK (2) Undescribed Gone: described, not on disk Connector package importing only the SDK Released together, in one deploy
Deployed as production, staging, local One release: the Worker cockpit Served by the Worker as static assets; it talks to the API over HTTP and live updates, in the shapes of packages/shared. Web app One Cloudflare Worker. worker.ts dispatches fetch, queue and scheduled; the Hono app handles requests. API Shared by the web app and the API. Packages One box per source the description file declares Connectors web imports shared in 67 files http imports mcp in 1 file http imports engines in 1 file mcp imports jobs in 1 file jobs imports connectors in 1 file jobs imports ai in 1 file engines imports auth in 1 file connectors imports auth in 2 files connectors imports Microsoft Teams in 1 file connectors imports Gmail in 1 file auth imports accounts in 3 files ai imports gateway in 1 file ai imports domain in 3 files accounts imports embeddings in 1 file accounts imports domain in 9 files accounts imports db in 2 files accounts imports connector-sdk in 6 files embeddings imports gateway in 1 file gateway imports shared in 1 file domain imports shared in 12 files db imports shared in 1 file Microsoft Teams imports connector-sdk in 3 files Gmail imports connector-sdk in 4 files connector-sdk imports shared in 1 file Claude Code code in web: components/ConnectClaudeCode.tsx Claude Code code in engines: claude-code-hooks.ts, claude-code.ts Teams app is part of Microsoft Teams's package The React app: router, pages, panels, Inbox, Capture and its offline outbox, item form, settings and connections. web 37,714 lines The Hono app: every route, request validation, error-to-status mapping and the live-update stream. http 2,640 lines Sign-in with OIDC, sessions, the gate in front of every route, operator and admin access, attachment links. auth 2,248 lines The MCP server at /mcp: OAuth for connected apps, consent, grants and the create_item tool. mcp 1,011 lines The queue consumer that cleans up and reads captured notes, and the nightly scheduled work. jobs 1,811 lines Claude Code, the one outbound engine: the trigger check, the fire request, its refusal wording and reading a hook, reached only through engines/list.ts. engines 310 lines The Claude layer behind a project-owned interface: prompts that clean up a note and choose a panel. ai 1,166 lines Reads what a note means with Workers AI, so a note that repeats another can be flagged. embeddings 219 lines Makes and retries every paid provider call, and records each attempt in D1 for 12 months. gateway 317 lines The AccountStore Durable Object, one per account: its SQLite schema, change log, command service, backup and restore. accounts 18,529 lines The account data model as plain code: items, panels, dashboards, filings, workspaces and the histories behind them. domain 2,419 lines The register in D1 (accounts, users, sign-ins, connector directory): its Drizzle schema and client. db 398 lines The composition root where the core meets connectors, with the host connectors run against and the credential crypto. connectors 1,118 lines The Worker entry points (worker.ts, index.ts), its bindings type (env.ts) and the share target. env.ts, worker.ts 404 lines The contract between web and API: domain types, Zod schemas, command definitions and API shapes. shared 3,498 lines The connector SPI: what a connector is and the only capabilities the host offers it. connector-sdk 385 lines Shared tsconfig and formatting config for the monorepo; no code runs from it. config 7 lines Gmail, in packages/connectors/gmail Gmail 1,288 lines Imports ../../../scripts/lib/vitest-ses sion-reporter.mjs vitest.config.ts vitest.contract.config.ts Claude Code has no package of its own Claude Code No package of its own 3 files in the core Microsoft Teams, in packages/connectors/teams Microsoft Teams 600 lines Imports ../../../scripts/lib/vitest-ses sion-reporter.mjs vitest.config.ts vitest.contract.config.ts packages/connectors/teams/teams-app Released on its own Teams app Its manifest, zipped and uploaded to Teams by hand. 67 1 1 1 1 1 1 2 1 1 3 1 3 1 9 2 6 1 1 12 1 3 4 1 1 file 2 files

Dependencies

Each cell counts the files in the row's area importing the column's area, in dependency-chain order: each area stands above what it imports. The number beside a row is that area's source lines, tests excluded.

Imports an area below Imports an area above, against the order The other half of a cycle Muted: everything reads env.ts, worker.ts

The order is exact: every order of the 18 areas was weighed, up to 18. 0 import files point up.

webhttpmcpjobsenginesconnectorsauthaiaccountsembeddingsgatewaydomaindbconnectors/teamsconnectors/gmailconnector-sdksharedconfigenv.ts, worker.ts
web 37,71467
http 2,6401111111111
mcp 1,0111421136
jobs 1,811111522315
engines 310111
connectors 1,11823211156
auth 2,2483225
ai 1,1661321
accounts 18,5291926145
embeddings 21911
gateway 31712
domain 2,41912
db 3981
connectors/teams 6003
connectors/gmail 1,2884
connector-sdk 3851
shared 3,498
config 7
env.ts, worker.ts 40411211212

No two areas import each other.

Deployment Open full size →

Highlighted workflows deploy; the arrow goes to the environment they deploy. Each environment lists what it binds, under its own names; inherited marks a setting taken from the top of the Worker config.

GitHub michaelvanhoutte/cockpit Actions ci.yml · every merge +1 claude.yml · issue comment +3 codeql.yml · every merge +1 contract.yml · every pull request +2 deploy-harness-monitor.yml · every merge +1 deploy-production.yml · by hand deploy-staging.yml · every merge +1 nightly.yml · every night at 04:17 UTC +1 publish.yml · called by ci.yml, nightly.yml GitHub Pages published by publish.yml /test-explorer-report /stability/ci-stability-report /cycle-time/cycle-time-report /selection/test-selection-report /architecture/architecture-report Local development Wrangler environment local, Worker cockpit-local D1 databasecockpit R2 bucketcockpit-attachments KV namespacecockpit-oauth-local Durable ObjectAccountStore Queue, producercockpit-enrichment Queue, consumercockpit-enrichment Static assets../web/dist inherited Cron trigger0 3 * * * inherited Cloudflare account production deployed every merge and by hand (deploy-harness-monitor.yml +1) Worker cockpit D1 databasecockpit R2 bucketcockpit-attachments KV namespacec2a6d73caf0d43bfac75e175516e4df1 Durable ObjectAccountStore Queue, producercockpit-enrichment Queue, consumercockpit-enrichment Workers AIAI Static assets../web/dist Cron trigger0 3 * * * staging deployed every merge and by hand (deploy-staging.yml) Worker cockpit-staging D1 databasecockpit-staging R2 bucketcockpit-attachments-staging KV namespace40afd4f58c914507b7047737ee4d75bc Durable ObjectAccountStore Queue, producercockpit-enrichment-staging Queue, consumercockpit-enrichment-staging Workers AIAI Static assets../web/dist inherited Cron trigger0 3 * * * inherited