# godiao/dreamcoder architecture

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

- Interactive diagram: https://gitdiagram.com/godiao/dreamcoder
- Repository: https://github.com/godiao/dreamcoder

## Overview

DreamCoder is a local AI coding workbench: users configure a model provider, work in a desktop session, and inspect assistant output, tool calls, file changes, and terminal activity. The core runtime coordinates model turns and tools while retaining session state. Documented extensions include LAN browser access and MCP tools; IM adapters are present in the tree but the README describes them as roadmap work. The source excerpts show selected runtime relationships; several desktop-to-runtime links are inferred and marked unverified.

Main entry points: [`src/QueryEngine.ts`](https://github.com/godiao/dreamcoder/blob/main/src/QueryEngine.ts) (Turn Engine), [`desktop/src/App.tsx`](https://github.com/godiao/dreamcoder/blob/main/desktop/src/App.tsx) (Desktop UI), [`desktop/src/api/sessions.ts`](https://github.com/godiao/dreamcoder/blob/main/desktop/src/api/sessions.ts) (Session API), [`src/Tool.ts`](https://github.com/godiao/dreamcoder/blob/main/src/Tool.ts) (Tool Dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Workbench"]
  node_desktop_ui["Desktop UI<br/>[App.tsx]"]
  node_chat_view["Session Chat<br/>[ActiveSession.tsx]"]
  node_providers_ui["Provider Settings"]
  node_api_client["Desktop API<br/>[client.ts]"]
  node_session_api["Session API<br/>[sessions.ts]"]
  node_permissions["Permission UI"]
  node_terminal["Integrated Terminal<br/>[WorkspacePanel.tsx]"]
end

subgraph group_runtime["Agent Runtime"]
  node_engine["Turn Engine<br/>[QueryEngine.ts]"]
  node_query["Query Loop<br/>[query.ts]"]
  node_tools["Tool Dispatch<br/>[Tool.ts]"]
  node_commands["Commands<br/>[commands.ts]"]
end

subgraph group_state["Session State"]
  node_app_state["Runtime State<br/>[state.ts]"]
  node_session_storage[("Session Storage<br/>[sessionStorage.ts]")]
  node_result_storage[("Tool Results")]
end

subgraph group_integrations["External Access"]
  node_h5["LAN Browser"]
  node_mcp["MCP Manager"]
  node_mcp_services{{"MCP Services"}}
  node_model_provider{{"Model Provider"}}
end

node_user(("Developer"))
node_phone(("Phone Browser"))

node_user -->|"uses"| node_desktop_ui
node_desktop_ui -.->|"opens session"| node_chat_view
node_providers_ui -->|"configures"| node_model_provider
node_chat_view -.->|"requests session"| node_session_api
node_session_api -.->|"uses"| node_api_client
node_session_api -.->|"starts turns"| node_engine
node_engine -->|"runs loop"| node_query
node_engine -->|"loads commands"| node_commands
node_query -.->|"dispatches"| node_tools
node_engine -->|"reads state"| node_app_state
node_engine -->|"flushes"| node_session_storage
node_tools -->|"stores results"| node_result_storage
node_tools -.->|"requests approval"| node_permissions
node_engine -.->|"sends turns"| node_model_provider
node_engine -.->|"uses tools"| node_mcp
node_mcp -->|"connects"| node_mcp_services
node_phone -->|"connects over LAN"| node_h5
node_h5 -->|"continues sessions"| node_desktop_ui
node_desktop_ui -->|"embeds"| node_terminal

click node_desktop_ui "https://github.com/godiao/dreamcoder/blob/main/desktop/src/App.tsx"
click node_chat_view "https://github.com/godiao/dreamcoder/blob/main/desktop/src/pages/ActiveSession.tsx"
click node_providers_ui "https://github.com/godiao/dreamcoder/blob/main/desktop/src/components/settings/ProviderSettings.tsx"
click node_api_client "https://github.com/godiao/dreamcoder/blob/main/desktop/src/api/client.ts"
click node_session_api "https://github.com/godiao/dreamcoder/blob/main/desktop/src/api/sessions.ts"
click node_engine "https://github.com/godiao/dreamcoder/blob/main/src/QueryEngine.ts"
click node_query "https://github.com/godiao/dreamcoder/blob/main/src/query.ts"
click node_tools "https://github.com/godiao/dreamcoder/blob/main/src/Tool.ts"
click node_commands "https://github.com/godiao/dreamcoder/blob/main/src/commands.ts"
click node_permissions "https://github.com/godiao/dreamcoder/blob/main/src/components/permissions/FilePermissionDialog/usePermissionHandler.ts"
click node_app_state "https://github.com/godiao/dreamcoder/blob/main/src/bootstrap/state.ts"
click node_session_storage "https://github.com/godiao/dreamcoder/blob/main/src/utils/sessionStorage.ts"
click node_result_storage "https://github.com/godiao/dreamcoder/blob/main/src/utils/toolResultStorage.ts"
click node_h5 "https://github.com/godiao/dreamcoder/blob/main/desktop/src/components/layout/H5ConnectionView.tsx"
click node_mcp "https://github.com/godiao/dreamcoder/blob/main/src/services/mcp/MCPConnectionManager.tsx"
click node_terminal "https://github.com/godiao/dreamcoder/blob/main/desktop/src/components/workspace/WorkspacePanel.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_desktop_ui,node_chat_view,node_providers_ui,node_api_client,node_session_api,node_permissions,node_terminal,node_phone toneBlue
class node_engine,node_query,node_tools,node_commands toneAmber
class node_app_state,node_session_storage,node_result_storage toneMint
class node_h5,node_mcp,node_mcp_services,node_model_provider toneRose
class node_user toneIndigo
```

## Components

### Desktop Workbench

- [Desktop UI](https://github.com/godiao/dreamcoder/blob/main/desktop/src/App.tsx): `desktop/src/App.tsx`
- [Session Chat](https://github.com/godiao/dreamcoder/blob/main/desktop/src/pages/ActiveSession.tsx): `desktop/src/pages/ActiveSession.tsx`
- [Provider Settings](https://github.com/godiao/dreamcoder/blob/main/desktop/src/components/settings/ProviderSettings.tsx): `desktop/src/components/settings/ProviderSettings.tsx`
- [Desktop API](https://github.com/godiao/dreamcoder/blob/main/desktop/src/api/client.ts): `desktop/src/api/client.ts`
- [Session API](https://github.com/godiao/dreamcoder/blob/main/desktop/src/api/sessions.ts): `desktop/src/api/sessions.ts`
- [Permission UI](https://github.com/godiao/dreamcoder/blob/main/src/components/permissions/FilePermissionDialog/usePermissionHandler.ts): `src/components/permissions/FilePermissionDialog/usePermissionHandler.ts`
- [Integrated Terminal](https://github.com/godiao/dreamcoder/blob/main/desktop/src/components/workspace/WorkspacePanel.tsx): `desktop/src/components/workspace/WorkspacePanel.tsx`

### Agent Runtime

- [Turn Engine](https://github.com/godiao/dreamcoder/blob/main/src/QueryEngine.ts): `src/QueryEngine.ts`
- [Query Loop](https://github.com/godiao/dreamcoder/blob/main/src/query.ts): `src/query.ts`
- [Tool Dispatch](https://github.com/godiao/dreamcoder/blob/main/src/Tool.ts): `src/Tool.ts`
- [Commands](https://github.com/godiao/dreamcoder/blob/main/src/commands.ts): `src/commands.ts`

### Session State

- [Runtime State](https://github.com/godiao/dreamcoder/blob/main/src/bootstrap/state.ts): `src/bootstrap/state.ts`
- [Session Storage](https://github.com/godiao/dreamcoder/blob/main/src/utils/sessionStorage.ts): `src/utils/sessionStorage.ts`
- [Tool Results](https://github.com/godiao/dreamcoder/blob/main/src/utils/toolResultStorage.ts): `src/utils/toolResultStorage.ts`

### External Access

- [LAN Browser](https://github.com/godiao/dreamcoder/blob/main/desktop/src/components/layout/H5ConnectionView.tsx): `desktop/src/components/layout/H5ConnectionView.tsx`
- [MCP Manager](https://github.com/godiao/dreamcoder/blob/main/src/services/mcp/MCPConnectionManager.tsx): `src/services/mcp/MCPConnectionManager.tsx`
- **MCP Services**
- **Model Provider**

### Other components

- **Developer**
- **Phone Browser**

## Connections

- Developer → Desktop UI: uses (evidence: `README.md`)
- Desktop UI → Session Chat: opens session
- Provider Settings → Model Provider: configures (evidence: `README.md`)
- Session Chat → Session API: requests session
- Session API → Desktop API: uses
- Session API → Turn Engine: starts turns
- Turn Engine → Query Loop: runs loop (evidence: `src/QueryEngine.ts`)
- Turn Engine → Commands: loads commands (evidence: `src/QueryEngine.ts`)
- Query Loop → Tool Dispatch: dispatches
- Turn Engine → Runtime State: reads state (evidence: `src/QueryEngine.ts`)
- Turn Engine → Session Storage: flushes (evidence: `src/QueryEngine.ts`)
- Tool Dispatch → Tool Results: stores results (evidence: `src/Tool.ts`)
- Tool Dispatch → Permission UI: requests approval (evidence: `src/components/permissions/FilePermissionDialog/usePermissionHandler.ts`)
- Turn Engine → Model Provider: sends turns
- Turn Engine → MCP Manager: uses tools
- MCP Manager → MCP Services: connects (evidence: `README.md`)
- Phone Browser → LAN Browser: connects over LAN (evidence: `README.md`)
- LAN Browser → Desktop UI: continues sessions (evidence: `README.md`)
- Desktop UI → Integrated Terminal: embeds (evidence: `README.md`)
