Cacheboard is a Windows-local personal operations system with a Docker-isolated metrics service and a separate host-native orchestration broker. Its three owner-facing areas share navigation and exact identity bindings, but they do not share authority indiscriminately.
For binding decisions, read ADR 0001, ADR 0002, ADR 0006, ADR 0007, and ADR 0008. This page is the compact system map, not a replacement for those contracts.
flowchart LR
L["Start Cacheboard.cmd"] --> S["Windows startup supervisor"]
S --> D["Metrics Dashboard container :8787"]
S --> O["Windows-local Orchestrator :8790"]
D -->|"one-time authenticated bridge"| O
O --> C["Orchestrator Command Center"]
O --> T["Cacheboard Tasks /tasks"]
D --> P["Read-only Claude profiles"]
O --> X["Authoritative Windows Codex profiles"]
O --> M["Atomic signed Codex metrics snapshot"]
M -->|"read-only bridge"| D
O --> A["Exact-profile provider adapters"]
O --> G["Route-scoped read-only GitHub API evidence"]
O --> Q["SQLite schema 11: sessions, queues, Rooms, automations, Work Items, Quick Notes"]
- The Dashboard container owns owner-configured cards and Claude collection, and it verifies/projects the read-only Codex metrics snapshot. It is loopback-published by default and has no Codex executable, credential mount, or writer.
- The Orchestrator is a Windows-local process because it needs bounded access to native provider CLIs, repositories, worktrees, host agents, and local process custody.
- Windows Orchestrator is the sole active Codex credential writer. It refreshes and verifies the fixed Windows profiles, collects metrics through the pinned app-server, and atomically publishes the authenticated snapshot consumed by Dashboard.
- Cacheboard Tasks is a first-class product area, but not a third backend. It is the
/tasksprojection of current Orchestrator schema 11: the unchanged schema-10 Work Item domain plus the separate Quick Notes domain. - The Dashboard-to-Orchestrator browser transition uses a short-lived, single-use ticket in the loopback path. Dashboard/provider credentials never enter the URL. The resulting exact-origin signed Orchestrator session is delivered once in the URL fragment, removed from browser history immediately, and retained only in origin-scoped
sessionStorage.
See the runtime artifact identity contract for safe lifecycle replacement and the data/security model for trust boundaries and retention.
The registry has four stable identities—earl, bbpyderz, ehayestrainer, and claude—and exactly two providers per identity: Claude and Codex. The result is eight provider lanes. The Dashboard always projects those eight fixed rows; connection truth is separate from each reading's intent, authority, availability, and freshness, so a healthy connection never proves a current meter reading.
- A lane binds identity, isolated profile, provider, and capacity. It is not a single chat slot.
- Many exact sessions may exist inside one lane; every mutation targets an exact Cacheboard session ID.
- The verified email is evidence for an identity. A friendly label, plan, project, host, folder name, or session title is never an identity key.
- Cross-provider profiles under one stable ID must resolve to the same verified email.
- Work Items, projects, Rooms, automations, hosts, and connectors reuse these lanes. They cannot add identities or bypass lane admission.
The complete identity/profile and metrics contract is in server/README.md; the multi-session control contract is in ADR 0002.
| Area | Owner-facing responsibility | Authoritative state | Important boundary |
|---|---|---|---|
| Metrics Dashboard | Usage/activity readings, Azure and custom cards, layout and trends | Validated browser card configuration, read-only Claude profile inputs, and a verified Codex signed-snapshot projection | Has no Codex runtime or credential authority; does not run the orchestration control plane |
| Cacheboard Orchestrator | Sessions, capacity/admission, encrypted queued actions, Rooms/worktrees, automations, attention, host fabric, connectors, Tools & Memory, and Codex metric publication | Orchestrator SQLite, authoritative Windows Codex profiles, signed metric snapshots, and exact adapter/runtime receipts | Sole Codex credential/metrics writer plus capability- and owner-gated control of exact sessions |
| Cacheboard Tasks | Capture, Focus, six-column Kanban flow, projects/filters/views, detail/activity, reversible Archive/Trash, quick execution proposals, and private Quick Notes | Schema-10 Work Item tables/events plus separate schema-11 Quick Note tables in Orchestrator SQLite | Task/note text and links are context only; Quick Notes are human-only, reversible/no-purge, and grant no provider, filesystem, Room, or automation authority |
Tasks uses one personal board with Inbox, Next, Doing, Blocked, Review, and Done. Projects are filters, not separate boards. The compact interface keeps capture, search, filters, the collapsible Now/Risk rail, Quick Notes, and quick actions close to the board. Detailed Work Item and Quick Note schema, DTO, SSE, lifecycle, and authority rules live only in work-items.md; the decision rationale is in ADR 0007.
- The repository launcher delegates to
server/start-cacheboard.ps1. - The supervisor verifies paths, Docker availability, owned runtime identity, configuration, and exact account roster before exposing an authenticated browser session.
- Windows Orchestrator is the sole active Codex credential writer: it verifies and refreshes exact Windows profiles, then atomically publishes one authenticated HMAC-signed normalized snapshot for the Dashboard to read. Claude recovery first attempts the bounded native refresh path and verifies the exact configured identity before atomic promotion; browser login is reserved for a locally unusable refresh state or explicit owner action.
- The Orchestrator starts separately and accepts the Dashboard bridge only through an authenticated, short-lived ticket.
- A stale Orchestrator is replaced only when exact ownership, artifact identity, and idle state are all proven. Otherwise startup leaves it untouched and reports the boundary.
Startup/auth implementation details and operator recovery belong in server/README.md, multi-account operations, and the operator runbook.
| Concern | Primary source | Nearest verification |
|---|---|---|
| Metrics page and browser card state | index.html |
Server UI/security tests and full gate |
| Dashboard HTTP/auth/provider collection | server/server.mjs |
server/*.test.mjs |
| Startup and bounded runtime recovery | server/start-cacheboard.ps1 |
server/startup-*.test.ps1 and runtime-integrity tests |
| Claude credential refresh transaction | server/claude-refresh.ps1, server/setup-claude-profiles.ps1 |
Claude refresh/setup PowerShell tests |
| Codex profile enrollment, refresh, and signed metrics snapshot | server/setup-codex-profiles.ps1, orchestrator/src/codex-metrics-service.mjs |
Codex setup/runtime and snapshot-contract tests |
| Dashboard container and dormant rollback custody | server/docker-compose.yml |
Startup Docker tests and build gate |
| Orchestrator entry/lifecycle | orchestrator/bin/cacheboard-orchestrator.mjs, orchestrator/src/broker.mjs |
core.test.mjs, lifecycle.test.mjs, startup-integrity.test.mjs |
| Orchestrator database/schema | orchestrator/src/database.mjs |
migration, maintenance, store, and restart tests |
| HTTP/auth/browser surfaces | orchestrator/src/http-server.mjs, orchestrator/public/ |
HTTP, UI-contract, browser-fixture, and security tests |
| Work Items/Tasks behavior | orchestrator/src/work-items.mjs, orchestrator/public/app.js, orchestrator/public/styles.css |
work-items-*.test.mjs and ui-contract.test.mjs |
| Quick Notes behavior | orchestrator/src/quick-notes.mjs, orchestrator/src/database.mjs, orchestrator/src/http-server.mjs, shared Tasks assets |
quick-notes-*.test.mjs, maintenance/startup tests, and the Work Items browser fixture |
| GitHub API identity evidence | orchestrator/src/github-identity.mjs, route-scoped HTTP/UI resource |
github-identity*.test.mjs, startup, HTTP, UI-contract, and browser-fixture tests |
| Scheduling and execution admission | orchestrator/src/dispatch-scheduler.mjs |
scheduler, capacity-routing, and Work Items execution tests |
| Automation engine | orchestrator/src/automations.mjs |
automation durability/recovery and Work Items automation tests |
This map names ownership hotspots, not every dependency. Search callers and tests before editing a shared file; broker.mjs, database.mjs, http-server.mjs, and the three Orchestrator public assets are high-conflict paths.
- Provider credentials remain in owner-protected, gitignored profile/runtime custody and are never returned to browser code.
- Windows Orchestrator is the sole active Codex credential writer. The Dashboard reads only its authenticated HMAC-signed snapshot and must never mount or automatically reactivate dormant Docker Codex credentials while a Windows writer exists.
- The former Docker Codex runtime volume is preserved unmounted as dormant rollback custody, never an implicit fallback or automatic reactivation path. An owner-reviewed rollback deliberately stops the Windows writer and transfers authority before mounting it. Never run
docker compose -f server/docker-compose.yml down -v; routine operations must not delete the named volume. - Loopback and exact-origin authentication are defaults. Remote/mobile access uses its explicit paired tailnet gateway, not a widened generic listener.
- Queue payloads, session control, provider approvals, repository writers, path leases, and host commands each retain their own validators and audit trail.
- A Work Item resource link always has
authority = context_only. A link to a session, Room, recipe, run, host, or project cannot adopt it, approve it, create membership, grant a lease, or authorize provider/filesystem effects. - Provider and remote capabilities are versioned and fail closed. Unsupported operations are shown as unavailable/observed/handoff, never simulated as direct control.
- Public DTOs are allowlists. Do not serialize raw database rows or expose internal credential/path fields through convenience object spreading.
Cacheboard is not a generic identity manager, remote shell, Docker socket, browser automation takeover layer, unlimited provider-capacity pool, or autonomous approval system. It does not seize active consumer/provider clients, infer authority from model output, or treat fixture proof as live acceptance. The exact disposition for known surfaces is maintained in the universal control-plane map and provider capability matrix.