# johnreginald/donewhen architecture

> Architecture diagram of the GitHub repository johnreginald/donewhen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnreginald/donewhen
- Repository: https://github.com/johnreginald/donewhen

## Overview

DoneWhen is a self-hosted, multi-workspace tracker for work built by AI agents. People and agents create and update tickets; the server persists workspace-scoped work and enforces the done-when checklist gate before review or completion. Humans review tickets in the Inbox, approve or send them back, and can revisit the specs, documents, diagrams, and activity later. The product also provides boards, filters and saved views, MCP tools, Claude Code integration, live updates, and Web Push. Source excerpts show the server, persistence, event, and transport layers; some feature links rely on README documentation.

Main entry points: [`web/src/lib/store.js`](https://github.com/johnreginald/donewhen/blob/main/web/src/lib/store.js) (Client state), [`internal/api/server.go`](https://github.com/johnreginald/donewhen/blob/main/internal/api/server.go) (HTTP server), [`internal/store/store.go`](https://github.com/johnreginald/donewhen/blob/main/internal/store/store.go) (Workspace persistence), [`internal/service/service.go`](https://github.com/johnreginald/donewhen/blob/main/internal/service/service.go) (Domain service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser application"]
  node_browser["PWA interface<br/>[+layout.svelte]"]
  node_clientstate["Client state<br/>[store.js]"]
  node_apiclient["REST client<br/>[api.js]"]
  node_board["Board and views<br/>[+page.svelte]"]
  node_ticket["Ticket details<br/>[+page.svelte]"]
  node_inbox["Review inbox<br/>[+page.svelte]"]
  node_artifacts["Docs and diagrams<br/>[+page.svelte]"]
end

subgraph group_api["HTTP and agent access"]
  node_plugin["Claude Code menu<br/>[register.tsx]"]
  node_server["HTTP server<br/>[server.go]"]
  node_handlers["REST handlers"]
  node_auth["Identity and access<br/>[middleware.go]"]
  node_mcp["MCP tools<br/>[mcp.go]"]
end

subgraph group_domain["Workflow domain"]
  node_service["Domain service<br/>[service.go]"]
  node_gate["Done-when gate<br/>[gate.go]"]
  node_workflows["Workflow features"]
end

subgraph group_persistence["Persistence"]
  node_store["Workspace persistence<br/>[store.go]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_updates["Live notifications"]
  node_events["Event bus<br/>[events.go]"]
  node_sse["SSE stream<br/>[sse.go]"]
  node_push["Web Push<br/>[push.go]"]
  node_pushservice["Push service"]
end

node_person(("Human user"))
node_agent(("AI agent"))

node_person -->|"uses"| node_browser
node_browser -->|"interacts"| node_clientstate
node_clientstate -->|"calls"| node_apiclient
node_clientstate -.->|"feeds"| node_board
node_clientstate -.->|"feeds"| node_ticket
node_clientstate -.->|"feeds"| node_inbox
node_clientstate -.->|"feeds"| node_artifacts
node_agent -->|"calls tools"| node_mcp
node_agent -->|"uses"| node_plugin
node_plugin -->|"calls REST"| node_server
node_apiclient -.->|"calls REST"| node_server
node_server -->|"routes requests"| node_handlers
node_server -->|"configures"| node_auth
node_server -->|"mounts endpoint"| node_mcp
node_handlers -.->|"mutates issues"| node_service
node_mcp -->|"mutates issues"| node_service
node_service -->|"persists changes"| node_store
node_service -->|"publishes events"| node_events
node_store -.->|"checks moves"| node_gate
node_store -->|"reads and writes"| node_postgres
node_store -.->|"supports features"| node_workflows
node_events -->|"streams events"| node_sse
node_events -->|"notifies subscriber"| node_push
node_push -->|"sends notifications"| node_pushservice
node_sse -.->|"updates live state"| node_clientstate

click node_browser "https://github.com/johnreginald/donewhen/blob/main/web/src/routes/%2Blayout.svelte"
click node_clientstate "https://github.com/johnreginald/donewhen/blob/main/web/src/lib/store.js"
click node_apiclient "https://github.com/johnreginald/donewhen/blob/main/web/src/lib/api.js"
click node_board "https://github.com/johnreginald/donewhen/blob/main/web/src/routes/board/%2Bpage.svelte"
click node_ticket "https://github.com/johnreginald/donewhen/blob/main/web/src/routes/issue/%5Bkey%5D/%2Bpage.svelte"
click node_inbox "https://github.com/johnreginald/donewhen/blob/main/web/src/routes/inbox/%2Bpage.svelte"
click node_artifacts "https://github.com/johnreginald/donewhen/blob/main/web/src/routes/artifacts/%2Bpage.svelte"
click node_plugin "https://github.com/johnreginald/donewhen/blob/main/plugin/hooks/register.tsx"
click node_server "https://github.com/johnreginald/donewhen/blob/main/internal/api/server.go"
click node_handlers "https://github.com/johnreginald/donewhen/tree/main/internal/api"
click node_auth "https://github.com/johnreginald/donewhen/blob/main/internal/auth/middleware.go"
click node_mcp "https://github.com/johnreginald/donewhen/blob/main/internal/mcp/mcp.go"
click node_service "https://github.com/johnreginald/donewhen/blob/main/internal/service/service.go"
click node_gate "https://github.com/johnreginald/donewhen/blob/main/internal/store/gate.go"
click node_workflows "https://github.com/johnreginald/donewhen/tree/main/internal/store"
click node_store "https://github.com/johnreginald/donewhen/blob/main/internal/store/store.go"
click node_events "https://github.com/johnreginald/donewhen/blob/main/internal/events/events.go"
click node_sse "https://github.com/johnreginald/donewhen/blob/main/internal/sse/sse.go"
click node_push "https://github.com/johnreginald/donewhen/blob/main/internal/push/push.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_clientstate,node_apiclient,node_board,node_ticket,node_inbox,node_artifacts,node_person toneBlue
class node_plugin,node_server,node_handlers,node_auth,node_mcp toneAmber
class node_service,node_gate,node_workflows toneMint
class node_store,node_postgres toneRose
class node_events,node_sse,node_push,node_pushservice,node_agent toneIndigo
```

## Components

### Browser application

- [PWA interface](https://github.com/johnreginald/donewhen/blob/main/web/src/routes/%2Blayout.svelte): `web/src/routes/+layout.svelte`
- [Client state](https://github.com/johnreginald/donewhen/blob/main/web/src/lib/store.js): `web/src/lib/store.js`
- [REST client](https://github.com/johnreginald/donewhen/blob/main/web/src/lib/api.js): `web/src/lib/api.js`
- [Board and views](https://github.com/johnreginald/donewhen/blob/main/web/src/routes/board/%2Bpage.svelte): `web/src/routes/board/+page.svelte`
- [Ticket details](https://github.com/johnreginald/donewhen/blob/main/web/src/routes/issue/%5Bkey%5D/%2Bpage.svelte): `web/src/routes/issue/[key]/+page.svelte`
- [Review inbox](https://github.com/johnreginald/donewhen/blob/main/web/src/routes/inbox/%2Bpage.svelte): `web/src/routes/inbox/+page.svelte`
- [Docs and diagrams](https://github.com/johnreginald/donewhen/blob/main/web/src/routes/artifacts/%2Bpage.svelte): `web/src/routes/artifacts/+page.svelte`

### HTTP and agent access

- [Claude Code menu](https://github.com/johnreginald/donewhen/blob/main/plugin/hooks/register.tsx): `plugin/hooks/register.tsx`
- [HTTP server](https://github.com/johnreginald/donewhen/blob/main/internal/api/server.go): `internal/api/server.go`
- [REST handlers](https://github.com/johnreginald/donewhen/tree/main/internal/api): `internal/api`
- [Identity and access](https://github.com/johnreginald/donewhen/blob/main/internal/auth/middleware.go): `internal/auth/middleware.go`
- [MCP tools](https://github.com/johnreginald/donewhen/blob/main/internal/mcp/mcp.go): `internal/mcp/mcp.go`

### Workflow domain

- [Domain service](https://github.com/johnreginald/donewhen/blob/main/internal/service/service.go): `internal/service/service.go`
- [Done-when gate](https://github.com/johnreginald/donewhen/blob/main/internal/store/gate.go): `internal/store/gate.go`
- [Workflow features](https://github.com/johnreginald/donewhen/tree/main/internal/store): `internal/store`

### Persistence

- [Workspace persistence](https://github.com/johnreginald/donewhen/blob/main/internal/store/store.go): `internal/store/store.go`
- **PostgreSQL**

### Live notifications

- [Event bus](https://github.com/johnreginald/donewhen/blob/main/internal/events/events.go): `internal/events/events.go`
- [SSE stream](https://github.com/johnreginald/donewhen/blob/main/internal/sse/sse.go): `internal/sse/sse.go`
- [Web Push](https://github.com/johnreginald/donewhen/blob/main/internal/push/push.go): `internal/push/push.go`
- **Push service**

### Other components

- **Human user**
- **AI agent**

## Connections

- Human user → PWA interface: uses (evidence: `README.md`)
- PWA interface → Client state: interacts (evidence: `web/src/routes/+layout.svelte`)
- Client state → REST client: calls (evidence: `web/src/lib/store.js`)
- Client state → Board and views: feeds
- Client state → Ticket details: feeds
- Client state → Review inbox: feeds
- Client state → Docs and diagrams: feeds
- AI agent → MCP tools: calls tools (evidence: `README.md`)
- AI agent → Claude Code menu: uses (evidence: `README.md`)
- Claude Code menu → HTTP server: calls REST (evidence: `README.md`)
- REST client → HTTP server: calls REST
- HTTP server → REST handlers: routes requests (evidence: `internal/api/server.go`)
- HTTP server → Identity and access: configures (evidence: `internal/api/server.go`)
- HTTP server → MCP tools: mounts endpoint
- REST handlers → Domain service: mutates issues
- MCP tools → Domain service: mutates issues (evidence: `internal/mcp/mcp.go`)
- Domain service → Workspace persistence: persists changes (evidence: `internal/service/service.go`)
- Domain service → Event bus: publishes events (evidence: `internal/service/service.go`)
- Workspace persistence → Done-when gate: checks moves
- Workspace persistence → PostgreSQL: reads and writes (evidence: `internal/store/store.go`)
- Workspace persistence → Workflow features: supports features
- Event bus → SSE stream: streams events (evidence: `internal/sse/sse.go`)
- Event bus → Web Push: notifies subscriber (evidence: `internal/push/push.go`)
- Web Push → Push service: sends notifications (evidence: `internal/push/push.go`)
- SSE stream → Client state: updates live state
