# cakahlul/odwyn architecture

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

- Interactive diagram: https://gitdiagram.com/cakahlul/odwyn
- Repository: https://github.com/cakahlul/odwyn

## Overview

Odwyn is a self-hosted AI-agent workspace. Users configure agents and providers, then send goals to an agent or collaborative room; the runtime coordinates provider turns and tools, and users review results, approvals, and activity. Reusable workflows and skills, browser takeover, knowledge, files, workspace management, and Oddy extend that core. The excerpts show selected calls and imports; other documented capabilities are included without asserting unsampled implementation links.

Main entry points: [`runtime.js`](https://github.com/cakahlul/odwyn/blob/main/runtime.js) (Job runtime), [`public/app.js`](https://github.com/cakahlul/odwyn/blob/main/public/app.js) (Web application), [`server.js`](https://github.com/cakahlul/odwyn/blob/main/server.js) (HTTP application), [`store.js`](https://github.com/cakahlul/odwyn/blob/main/store.js) (Workspace store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Workspace experience"]
  node_webapp["Web application<br/>[app.js]"]
  node_workspaceui["Workspace interface<br/>[ui.js]"]
  node_chatviews["Chat and room views<br/>[views.js]"]
  node_workflowui["Workflow interface<br/>[workflows-ui.js]"]
  node_auditui["Activity interface<br/>[audit-ui.js]"]
  node_connectionsui["Connections interface<br/>[connections-ui.js]"]
end

subgraph group_orchestration["Task orchestration"]
  node_http["HTTP application<br/>[server.js]"]
  node_runtime["Job runtime<br/>[runtime.js]"]
  node_rooms["Room coordination<br/>[room-work.js]"]
  node_roomstages["Room stages<br/>[room-stages.js]"]
  node_workflowengine["Workflow engine<br/>[workflows.js]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_browser["Persistent browser<br/>[browser.js]"]
  node_terminal["Host terminal<br/>[terminal.js]"]
  node_files["Workspace files<br/>[files.js]"]
  node_knowledge["Knowledge and search<br/>[knowledge.js]"]
  node_oddy["Oddy assistant<br/>[oddy.js]"]
end

subgraph group_persistence["Workspace data"]
  node_store[("Workspace store<br/>[store.js]")]
  node_security["Security controls<br/>[security.js]"]
  node_audit[("Audit history<br/>[audit.js]")]
  node_reports["Conversation reports"]
end

subgraph group_integrations["Providers and services"]
  node_providers["Provider gateway<br/>[providers.js]"]
  node_codex["Codex adapter<br/>[codex.js]"]
  node_antigravity["Antigravity adapter<br/>[antigravity.js]"]
  node_proxy["Browser proxy<br/>[proxy.js]"]
  node_usage["Usage accounting<br/>[usage.js]"]
  node_connections["Provider connections<br/>[connections.js]"]
end

node_user(("Workspace user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"sets up"| node_workflowui
node_webapp -->|"sets up"| node_auditui
node_webapp -->|"sets up"| node_connectionsui
node_webapp -->|"renders"| node_chatviews
node_webapp -->|"uses"| node_workspaceui
node_workflowui -->|"runs workflows"| node_http
node_http -->|"dispatches jobs"| node_runtime
node_http -->|"uses"| node_store
node_http -->|"validates input"| node_security
node_http -->|"manages connections"| node_connections
node_http -->|"serves reports"| node_reports
node_runtime -->|"executes turns"| node_providers
node_runtime -->|"runs steps"| node_workflowengine
node_runtime -->|"coordinates rooms"| node_rooms
node_runtime -->|"advances stages"| node_roomstages
node_runtime -->|"saves state"| node_store
node_runtime -->|"delegates assistant"| node_oddy
node_runtime -->|"uses files"| node_files
node_runtime -->|"runs commands"| node_terminal
node_runtime -->|"uses knowledge"| node_knowledge
node_rooms -->|"uses stages"| node_roomstages
node_rooms -->|"reads state"| node_store
node_rooms -->|"uses files"| node_files
node_providers -->|"delegates"| node_codex
node_providers -->|"delegates"| node_antigravity
node_providers -->|"records usage"| node_usage
node_browser -->|"starts proxy"| node_proxy
node_browser -->|"validates navigation"| node_security
node_store -->|"opens audit"| node_audit
node_store -->|"opens knowledge"| node_knowledge
node_store -->|"validates data"| node_security
node_connectionsui -->|"uses"| node_workflowui
node_auditui -->|"uses"| node_workspaceui
node_chatviews -->|"uses"| node_workspaceui
node_user -.->|"takes over browsing"| node_browser
node_user -.->|"reuses routines"| node_workflowengine

click node_webapp "https://github.com/cakahlul/odwyn/blob/main/public/app.js"
click node_workspaceui "https://github.com/cakahlul/odwyn/blob/main/public/ui.js"
click node_chatviews "https://github.com/cakahlul/odwyn/blob/main/public/views.js"
click node_workflowui "https://github.com/cakahlul/odwyn/blob/main/public/workflows-ui.js"
click node_auditui "https://github.com/cakahlul/odwyn/blob/main/public/audit-ui.js"
click node_connectionsui "https://github.com/cakahlul/odwyn/blob/main/public/connections-ui.js"
click node_http "https://github.com/cakahlul/odwyn/blob/main/server.js"
click node_runtime "https://github.com/cakahlul/odwyn/blob/main/runtime.js"
click node_rooms "https://github.com/cakahlul/odwyn/blob/main/room-work.js"
click node_roomstages "https://github.com/cakahlul/odwyn/blob/main/room-stages.js"
click node_workflowengine "https://github.com/cakahlul/odwyn/blob/main/workflows.js"
click node_browser "https://github.com/cakahlul/odwyn/blob/main/browser.js"
click node_terminal "https://github.com/cakahlul/odwyn/blob/main/terminal.js"
click node_files "https://github.com/cakahlul/odwyn/blob/main/files.js"
click node_knowledge "https://github.com/cakahlul/odwyn/blob/main/knowledge.js"
click node_oddy "https://github.com/cakahlul/odwyn/blob/main/oddy.js"
click node_store "https://github.com/cakahlul/odwyn/blob/main/store.js"
click node_security "https://github.com/cakahlul/odwyn/blob/main/security.js"
click node_audit "https://github.com/cakahlul/odwyn/blob/main/audit.js"
click node_reports "https://github.com/cakahlul/odwyn/blob/main/conversation-reports.js"
click node_providers "https://github.com/cakahlul/odwyn/blob/main/providers.js"
click node_codex "https://github.com/cakahlul/odwyn/blob/main/codex.js"
click node_antigravity "https://github.com/cakahlul/odwyn/blob/main/antigravity.js"
click node_proxy "https://github.com/cakahlul/odwyn/blob/main/proxy.js"
click node_usage "https://github.com/cakahlul/odwyn/blob/main/usage.js"
click node_connections "https://github.com/cakahlul/odwyn/blob/main/connections.js"

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_webapp,node_workspaceui,node_chatviews,node_workflowui,node_auditui,node_connectionsui,node_user toneBlue
class node_http,node_runtime,node_rooms,node_roomstages,node_workflowengine toneAmber
class node_browser,node_terminal,node_files,node_knowledge,node_oddy toneMint
class node_store,node_security,node_audit,node_reports toneRose
class node_providers,node_codex,node_antigravity,node_proxy,node_usage,node_connections toneIndigo
```

## Components

### Workspace experience

- [Web application](https://github.com/cakahlul/odwyn/blob/main/public/app.js): `public/app.js`
- [Workspace interface](https://github.com/cakahlul/odwyn/blob/main/public/ui.js): `public/ui.js`
- [Chat and room views](https://github.com/cakahlul/odwyn/blob/main/public/views.js): `public/views.js`
- [Workflow interface](https://github.com/cakahlul/odwyn/blob/main/public/workflows-ui.js): `public/workflows-ui.js`
- [Activity interface](https://github.com/cakahlul/odwyn/blob/main/public/audit-ui.js): `public/audit-ui.js`
- [Connections interface](https://github.com/cakahlul/odwyn/blob/main/public/connections-ui.js): `public/connections-ui.js`

### Task orchestration

- [HTTP application](https://github.com/cakahlul/odwyn/blob/main/server.js): `server.js`
- [Job runtime](https://github.com/cakahlul/odwyn/blob/main/runtime.js): `runtime.js`
- [Room coordination](https://github.com/cakahlul/odwyn/blob/main/room-work.js): `room-work.js`
- [Room stages](https://github.com/cakahlul/odwyn/blob/main/room-stages.js): `room-stages.js`
- [Workflow engine](https://github.com/cakahlul/odwyn/blob/main/workflows.js): `workflows.js`

### Agent capabilities

- [Persistent browser](https://github.com/cakahlul/odwyn/blob/main/browser.js): `browser.js`
- [Host terminal](https://github.com/cakahlul/odwyn/blob/main/terminal.js): `terminal.js`
- [Workspace files](https://github.com/cakahlul/odwyn/blob/main/files.js): `files.js`
- [Knowledge and search](https://github.com/cakahlul/odwyn/blob/main/knowledge.js): `knowledge.js`
- [Oddy assistant](https://github.com/cakahlul/odwyn/blob/main/oddy.js): `oddy.js`

### Workspace data

- [Workspace store](https://github.com/cakahlul/odwyn/blob/main/store.js): `store.js`
- [Security controls](https://github.com/cakahlul/odwyn/blob/main/security.js): `security.js`
- [Audit history](https://github.com/cakahlul/odwyn/blob/main/audit.js): `audit.js`
- [Conversation reports](https://github.com/cakahlul/odwyn/blob/main/conversation-reports.js): `conversation-reports.js`

### Providers and services

- [Provider gateway](https://github.com/cakahlul/odwyn/blob/main/providers.js): `providers.js`
- [Codex adapter](https://github.com/cakahlul/odwyn/blob/main/codex.js): `codex.js`
- [Antigravity adapter](https://github.com/cakahlul/odwyn/blob/main/antigravity.js): `antigravity.js`
- [Browser proxy](https://github.com/cakahlul/odwyn/blob/main/proxy.js): `proxy.js`
- [Usage accounting](https://github.com/cakahlul/odwyn/blob/main/usage.js): `usage.js`
- [Provider connections](https://github.com/cakahlul/odwyn/blob/main/connections.js): `connections.js`

### Other components

- **Workspace user**

## Connections

- Workspace user → Web application: uses (evidence: `README.md`)
- Web application → Workflow interface: sets up (evidence: `public/app.js`)
- Web application → Activity interface: sets up (evidence: `public/app.js`)
- Web application → Connections interface: sets up (evidence: `public/app.js`)
- Web application → Chat and room views: renders (evidence: `public/app.js`)
- Web application → Workspace interface: uses (evidence: `public/app.js`)
- Workflow interface → HTTP application: runs workflows (evidence: `public/workflows-ui.js`)
- HTTP application → Job runtime: dispatches jobs (evidence: `server.js`)
- HTTP application → Workspace store: uses (evidence: `server.js`)
- HTTP application → Security controls: validates input (evidence: `server.js`)
- HTTP application → Provider connections: manages connections (evidence: `server.js`)
- HTTP application → Conversation reports: serves reports (evidence: `server.js`)
- Job runtime → Provider gateway: executes turns (evidence: `runtime.js`)
- Job runtime → Workflow engine: runs steps (evidence: `runtime.js`)
- Job runtime → Room coordination: coordinates rooms (evidence: `runtime.js`)
- Job runtime → Room stages: advances stages (evidence: `runtime.js`)
- Job runtime → Workspace store: saves state (evidence: `runtime.js`)
- Job runtime → Oddy assistant: delegates assistant (evidence: `runtime.js`)
- Job runtime → Workspace files: uses files (evidence: `runtime.js`)
- Job runtime → Host terminal: runs commands (evidence: `runtime.js`)
- Job runtime → Knowledge and search: uses knowledge (evidence: `runtime.js`)
- Room coordination → Room stages: uses stages (evidence: `room-work.js`)
- Room coordination → Workspace store: reads state (evidence: `room-work.js`)
- Room coordination → Workspace files: uses files (evidence: `room-work.js`)
- Provider gateway → Codex adapter: delegates (evidence: `providers.js`)
- Provider gateway → Antigravity adapter: delegates (evidence: `providers.js`)
- Provider gateway → Usage accounting: records usage (evidence: `providers.js`)
- Persistent browser → Browser proxy: starts proxy (evidence: `browser.js`)
- Persistent browser → Security controls: validates navigation (evidence: `browser.js`)
- Workspace store → Audit history: opens audit (evidence: `store.js`)
- Workspace store → Knowledge and search: opens knowledge (evidence: `store.js`)
- Workspace store → Security controls: validates data (evidence: `store.js`)
- Connections interface → Workflow interface: uses (evidence: `public/connections-ui.js`)
- Activity interface → Workspace interface: uses (evidence: `public/audit-ui.js`)
- Chat and room views → Workspace interface: uses (evidence: `public/views.js`)
- Workspace user → Persistent browser: takes over browsing (evidence: `README.md`)
- Workspace user → Workflow engine: reuses routines (evidence: `README.md`)
