# leonvanzyl/codeden architecture

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

- Interactive diagram: https://gitdiagram.com/leonvanzyl/codeden
- Repository: https://github.com/leonvanzyl/codeden

## Overview

CodeDen is a local-first coding-agent workspace with CLI and desktop launchers, a web UI, a local server, and a persistent runner. The main workflow is: a user sets up a project and starts a session; the server delegates work to an isolated agent session; runner events are stored and projected; the UI presents the transcript and workbench for review. The graph also preserves documented orchestration, inbox, GitHub, automation, and factory capabilities. Some feature wiring is unsampled, so those relationships rely on README statements rather than inspected implementation.

Main entry points: [`apps/server/src/server.ts`](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/server.ts) (Local server), [`apps/server/src/services/orchestration/orchestration-service.ts`](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/orchestration/orchestration-service.ts) (Agent orchestration), [`apps/server/src/services/sessions/session-service.ts`](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/sessions/session-service.ts) (Session lifecycle), [`apps/server/src/runner/client.ts`](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/runner/client.ts) (Runner protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_web["Web workspace<br/>[router.tsx]"]
  node_cli["CLI launcher<br/>[main.ts]"]
  node_desktop["Desktop app<br/>[main.ts]"]
end

subgraph group_runtime["Session runtime"]
  node_server["Local server<br/>[server.ts]"]
  node_projects["Project management<br/>[project-service.ts]"]
  node_sessions["Session lifecycle<br/>[session-service.ts]"]
  node_runner["Runner protocol<br/>[client.ts]"]
  node_runner_process["Runner process<br/>[main.ts]"]
  node_agent["Agent provider<br/>[session.ts]"]
  node_browser["Agent browser<br/>[manager.ts]"]
end

subgraph group_state["Events and state"]
  node_events["Event ingestion<br/>[ingest.ts]"]
  node_event_store[("Event store<br/>[store.ts]")]
  node_database[("SQLite database<br/>[client.ts]")]
end

subgraph group_coordination["Work coordination"]
  node_orchestration["Agent orchestration"]
  node_inbox["User inbox<br/>[inbox-service.ts]"]
  node_automation["Automations"]
  node_factory["Factory loop<br/>[factory-service.ts]"]
end

subgraph group_review["Workbench and integrations"]
  node_github["GitHub services<br/>[github-service.ts]"]
  node_workbench["Session workbench<br/>[browser-panel.tsx]"]
end

node_user(("User"))
node_external_github(("GitHub"))

node_user -->|"uses"| node_web
node_user -->|"starts"| node_cli
node_user -->|"uses"| node_desktop
node_web -.->|"requests"| node_server
node_cli -->|"starts"| node_server
node_desktop -->|"hosts"| node_server
node_server -.->|"manages"| node_projects
node_server -.->|"handles"| node_sessions
node_sessions -->|"delegates"| node_runner
node_runner -->|"connects"| node_runner_process
node_runner -->|"submits"| node_events
node_runner_process -->|"runs"| node_agent
node_runner_process -.->|"provides"| node_browser
node_events -->|"appends"| node_event_store
node_event_store -->|"persists"| node_database
node_server -.->|"coordinates"| node_orchestration
node_orchestration -->|"starts and steers"| node_sessions
node_orchestration -->|"reads"| node_inbox
node_server -.->|"runs"| node_automation
node_factory -->|"builds work"| node_sessions
node_factory -->|"notifies"| node_orchestration
node_github -.->|"syncs"| node_external_github
node_workbench -.->|"views session"| node_server
node_user -->|"reviews work"| node_workbench

click node_web "https://github.com/leonvanzyl/codeden/blob/main/apps/web/src/router.tsx"
click node_cli "https://github.com/leonvanzyl/codeden/blob/main/apps/cli/src/main.ts"
click node_desktop "https://github.com/leonvanzyl/codeden/blob/main/apps/desktop/src/main/main.ts"
click node_server "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/server.ts"
click node_projects "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/projects/project-service.ts"
click node_sessions "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/sessions/session-service.ts"
click node_runner "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/runner/client.ts"
click node_runner_process "https://github.com/leonvanzyl/codeden/blob/main/apps/runner/src/main.ts"
click node_agent "https://github.com/leonvanzyl/codeden/blob/main/packages/providers/src/claude/session.ts"
click node_browser "https://github.com/leonvanzyl/codeden/blob/main/apps/runner/src/browser/manager.ts"
click node_events "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/events/ingest.ts"
click node_event_store "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/events/store.ts"
click node_database "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/db/client.ts"
click node_orchestration "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/orchestration/orchestration-service.ts"
click node_inbox "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/inbox-service.ts"
click node_automation "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/automations/automation-service.ts"
click node_factory "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/factory/factory-service.ts"
click node_github "https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/github/github-service.ts"
click node_workbench "https://github.com/leonvanzyl/codeden/blob/main/apps/web/src/components/workbench/browser-panel.tsx"

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_web,node_cli,node_desktop,node_user toneBlue
class node_server,node_projects,node_sessions,node_runner,node_runner_process,node_agent,node_browser toneAmber
class node_events,node_event_store,node_database toneMint
class node_orchestration,node_inbox,node_automation,node_factory toneRose
class node_github,node_workbench,node_external_github toneIndigo
```

## Components

### User interfaces

- [Web workspace](https://github.com/leonvanzyl/codeden/blob/main/apps/web/src/router.tsx): `apps/web/src/router.tsx`
- [CLI launcher](https://github.com/leonvanzyl/codeden/blob/main/apps/cli/src/main.ts): `apps/cli/src/main.ts`
- [Desktop app](https://github.com/leonvanzyl/codeden/blob/main/apps/desktop/src/main/main.ts): `apps/desktop/src/main/main.ts`

### Session runtime

- [Local server](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/server.ts): `apps/server/src/server.ts`
- [Project management](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/projects/project-service.ts): `apps/server/src/services/projects/project-service.ts`
- [Session lifecycle](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/sessions/session-service.ts): `apps/server/src/services/sessions/session-service.ts`
- [Runner protocol](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/runner/client.ts): `apps/server/src/runner/client.ts`
- [Runner process](https://github.com/leonvanzyl/codeden/blob/main/apps/runner/src/main.ts): `apps/runner/src/main.ts`
- [Agent provider](https://github.com/leonvanzyl/codeden/blob/main/packages/providers/src/claude/session.ts): `packages/providers/src/claude/session.ts`
- [Agent browser](https://github.com/leonvanzyl/codeden/blob/main/apps/runner/src/browser/manager.ts): `apps/runner/src/browser/manager.ts`

### Events and state

- [Event ingestion](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/events/ingest.ts): `apps/server/src/events/ingest.ts`
- [Event store](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/events/store.ts): `apps/server/src/events/store.ts`
- [SQLite database](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/db/client.ts): `apps/server/src/db/client.ts`

### Work coordination

- [Agent orchestration](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/orchestration/orchestration-service.ts): `apps/server/src/services/orchestration/orchestration-service.ts`
- [User inbox](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/inbox-service.ts): `apps/server/src/services/inbox-service.ts`
- [Automations](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/automations/automation-service.ts): `apps/server/src/services/automations/automation-service.ts`
- [Factory loop](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/factory/factory-service.ts): `apps/server/src/services/factory/factory-service.ts`

### Workbench and integrations

- [GitHub services](https://github.com/leonvanzyl/codeden/blob/main/apps/server/src/services/github/github-service.ts): `apps/server/src/services/github/github-service.ts`
- [Session workbench](https://github.com/leonvanzyl/codeden/blob/main/apps/web/src/components/workbench/browser-panel.tsx): `apps/web/src/components/workbench/browser-panel.tsx`

### Other components

- **User**
- **GitHub**

## Connections

- User → Web workspace: uses
- User → CLI launcher: starts
- User → Desktop app: uses
- Web workspace → Local server: requests
- CLI launcher → Local server: starts (evidence: `apps/cli/src/main.ts`)
- Desktop app → Local server: hosts (evidence: `apps/desktop/src/main/main.ts`)
- Local server → Project management: manages
- Local server → Session lifecycle: handles
- Session lifecycle → Runner protocol: delegates (evidence: `apps/server/src/services/sessions/session-service.ts`)
- Runner protocol → Runner process: connects (evidence: `apps/server/src/runner/client.ts`)
- Runner protocol → Event ingestion: submits (evidence: `apps/server/src/runner/client.ts`)
- Runner process → Agent provider: runs
- Runner process → Agent browser: provides
- Event ingestion → Event store: appends (evidence: `apps/server/src/events/ingest.ts`)
- Event store → SQLite database: persists (evidence: `apps/server/src/events/store.ts`)
- Local server → Agent orchestration: coordinates
- Agent orchestration → Session lifecycle: starts and steers (evidence: `apps/server/src/services/orchestration/orchestration-service.ts`)
- Agent orchestration → User inbox: reads (evidence: `apps/server/src/services/orchestration/orchestration-service.ts`)
- Local server → Automations: runs
- Factory loop → Session lifecycle: builds work (evidence: `apps/server/src/services/factory/factory-service.ts`)
- Factory loop → Agent orchestration: notifies (evidence: `apps/server/src/services/factory/factory-service.ts`)
- GitHub services → GitHub: syncs
- Session workbench → Local server: views session
- User → Session workbench: reviews work