Architecture

Maintainer HQ is a local-first application with one active workspace per process. The CLI, loopback dashboard broker, and stdio MCP server all construct the same workspace service with an immutable document path, repository roots, environment roots, adapter configuration, and read or write authority.

CLI -----------+
Dashboard -----+--> workspace service --> private workspace document
MCP -----------+            +------------> private activity ledger
                            |
                            +--> bounded local inventory readers
                            +--> explicit optional provider adapters

Workspace boundary

The versioned JSON document is the source of truth. It carries a stable random workspace ID, a display name, creation metadata, repository records, provider intent, recovery state, and secret-consumer metadata. The ID identifies the logical workspace but is not a credential. A service instance never switches workspace during a request.

Local 0.1.0 operation has one implicit owner and one workspace per process. A future team service can place authentication and workspace selection in front of service construction, then map the same workspace-scoped operations to another storage implementation. Repository identity, mutation schemas, plan digests, and interface contracts do not depend on a home directory or personal account.

Read and write paths

Reads validate file type, permissions, size, identity, schema, and optional Git encryption before returning a normalized object. Every external interface derives a secret-free projection from that object. Browser and MCP consumers cannot request the raw document.

Local writes produce an exact plan bound to the current document revision and complete requested mutation. Secret-bearing requests retain values only in a bounded, expiring process-local plan store. Apply reacquires the document, validates the plan, obtains the adjacent lock, rereads the revision, and atomically replaces the file. Provider writes also rerun their adapter plan around confirmation and reject changed output.

Adapters

Adapters are explicit capabilities, not generic provider passthroughs. The GitHub audit and reconciliation commands receive private compatibility projections. Hookrelay receives a private manifest and retains its own phase and confirmation model. Endpoint Monitor contributes only a sanitized target-ID inventory. Adapter absence is a skipped diagnostic unless an operator invokes the dependent capability.

This narrow design preserves useful mature integrations while keeping the core install portable. New providers should expose domain operations with bounded schemas, safe read projections, exact planning, confirmation, verification, and recovery instead of accepting arbitrary commands or API paths.

Interface parity

Every operator capability belongs in src/operator-capabilities.mjs. A non-visual feature is incomplete until its CLI or broker outcome has equivalent purpose-built MCP coverage, tests, and documentation. The parity test rejects undeclared tools, orphan tools, and uncovered mutation kinds.

The dashboard remains a local view over the same service semantics. It binds to 127.0.0.1, uses a random session route and header, serves only bundled assets, and sends no workspace secrets or remote scripts to the browser.

Activity ledger and derived summaries

The activity ledger is a separate private, workspace-ID-bound sidecar because feed evidence changes more frequently than repository policy and can be rebuilt independently. Projects group existing workspace repository identities. Manual entries retain operator state and audit records, while bounded local Git and GitHub readers normalize commits, CI runs, and releases into stable source identities. Idempotent merge keeps corroborating sources together and preserves acknowledgement, pin, and archive state.

Optional AI summaries are derived records, never implicit provider access. A plan binds the activity revision, selected entries, disclosed fields, model, eligible private providers, token ceiling, pricing snapshot, conservative estimate, and operator limit. Apply revalidates the catalog and revision, persists a pending generation, then routes one request through the AI SDK and Vercel AI Gateway. Terminal records keep output, lineage, prompt hash, usage, and cost while excluding the raw prompt and provider diagnostics. A process-local active set prevents recovery from racing a live request; a later process can explicitly mark an abandoned pending receipt as aborted.

The core feed has no dependency on an AI credential or model response. Summary planning never calls a model, generation is always separately confirmed, and retries create new linked records instead of overwriting evidence.

Future security data

Security findings will retain provider identity, severity, lifecycle, affected repository, evidence timestamps, and operator state such as acknowledged, snoozed, or resolved. Alert delivery will consume normalized state transitions so repeated polling cannot create duplicate notifications.

Source layout

• src/ contains workspace, schema, service, CLI, MCP, broker, mutation, inventory, and adapter logic
• public/ contains dependency-light dashboard assets with no remote runtime dependencies
• test/ contains unit and integration coverage
• e2e/ contains browser workflows
• scripts/ contains hermetic checks, packaging, clean-install verification, and guarded release tooling
• docs/ contains durable operator and contributor contracts plus the build-time VitePress documentation portal
• wrangler.docs.jsonc defines a separate assets-only documentation Worker without application authority