saltbo__agent-kanban/docs/architecture/system-overview.md

System overview

Agent Kanban is a React SPA and Hono API deployed together as one Cloudflare Worker. D1 stores AK-owned business state. Human sign-in uses standard OIDC; Realmroot is the current provider and supplies the additional Agent identity and Toolbox integration. Agency provides runtime infrastructure, and AMA Runner hosts self-hosted execution.

Browser ───────────────► Agent Kanban Worker ─────────► D1
                           │       │
Realmroot Toolbox ─────────┘       ├────────► Agency
                                   └────────► Realmroot Inbox

AMA Runner ───────────► Agency

AK owns Boards, Repositories, Tasks, Notes, lifecycle state, review policy, public board views, and Task-to-Session observation bindings. Agency owns Projects, Identities, Agents, Environments, Runners, scheduling state, and Sessions. Inbox transports lifecycle notifications to assigned Agents.

The dependency direction is always AK to Agency, the configured OIDC provider, Realmroot's Agent/Toolbox extensions, and Inbox. See ADR 0005.

Runtime shape

src/                 React features and presentation
server/domain/       pure AK rules
server/usecases/     application operations and ports
server/adapters/     D1 and external service implementations
server/auth/         OIDC browser auth and Realmroot Agent authority
server/http/         routes, middleware, representations, OpenAPI
server/worker/       deployment entry point
shared/              shared wire types
migrations/          D1 schema history
spec/                product behavior
tests/               layered proofs

The detailed dependency and test placement rules are in code structure and test pyramid.