# hkuds/deepcode architecture

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

- Interactive diagram: https://gitdiagram.com/hkuds/deepcode
- Repository: https://github.com/hkuds/deepcode

## Overview

#### Purpose and entry points
DeepCode is a local, multi-interface coding-agent system for durable project work: agent turns can inspect/edit code, execute tools, gather verification evidence, and continue as Goals or scheduled Automations. The Python CLI/TUI and Tauri Desktop share canonical local state and the same agent runtime.
- CLI commands and interactive flows: `cli/automation_cli.py`, `cli/exec_cli.py`, `cli/tui/app.py`
- Desktop frontend and native host: `desktop/src/main.tsx`, `desktop/src-tauri/src/main.rs`
- Desktop launches a Python App Server sidecar: `app_server/__main__.py`, `app_server/server.py`

#### Application layer: durable work orchestration
`core/application` is the product-facing control plane over domain state, persistence, runtime execution, and management operations. It owns Projects, Threads/Sessions, Turns, Goals, approvals, workspaces, model configuration, automations, extensions, and projections consumed by clients.
- Main composition/application lifecycle: `core/application/application.py`, `core/application/session_runtime.py`
- Turn routing, admission, and execution coordination: `core/application/turn_service.py`, `core/application/execution_coordinator.py`, `core/application/interactive_turn_router.py`
- Domain records define stable concepts and policy inputs: `core/domain/thread.py`, `core/domain/turn.py`, `core/domain/execution_security.py`

Control flow is primarily: client submits a turn or goal → application admits it under a frozen security/execution profile → runtime emits events and durable records → clients replay/project thread state.

#### Agent runtime and supervised tool execution
The agent kernel resolves context, selected Skills/presets, tools, model calls, repeat protection, pruning, and multi-turn Goal behavior. Its harness is the critical safety boundary for local filesystem, shell, patch, web, and delegated-agent operations.
- Runtime loop and Goal continuation: `core/agent_runtime/runner.py`, `core/agent_runtime/goal_runtime.py`
- Tool registration and MCP bridging: `core/agent_runtime/tools/registry.py`, `core/agent_runtime/tools/mcp.py`
- Native capability implementations and sandbox/policy enforcement: `core/harness/tools/shell.py`, `core/harness/permissions.py`, `core/harness/sandbox.py`

Approvals suspend and later resume the exact tool request; read-only and explicit deny policies constrain tools. Process ownership, timeout, and cancellation boundaries protect execution.

#### State, coordination, and events
SQLite-backed persistence is the canonical source for projects, threads, turns/events, executions, workflows, automations, and coordination leases. This enables restart recovery and CLI/Desktop continuity rather than client-local histories.
- Database/migration boundary: `core/persistence/database.py`, `core/persistence/migrations.py`
- Thread/event and execution persistence: `core/persistence/thread_repository.py`, `core/persistence/event_repository.py`, `core/persistence/execution_repository.py`
- Event contracts and in-process observability: `core/events/protocol.py`, `core/observability/bus.py`

#### Model, Skills, Plugins, and MCP integrations
Provider adapters route inference to configured LLM endpoints while credentials remain in private storage. Skills and Plugins supply bounded instructions/capabilities without widening session permissions. MCP supports external tool servers through managed lifecycle and policy narrowing.
- Provider catalog, credentials, and OpenAI-compatible transport: `core/providers/catalog_service.py`, `core/providers/credentials.py`, `core/providers/openai_compat.py`
- Skill discovery/composition/runtime: `core/skills/host.py`, `core/skills/aggregation.py`, `core/skills/runtime.py`
- MCP connection/runtime and OAuth: `core/mcp/runtime.py`, `core/mcp/connection.py`, `core/mcp/oauth.py`
- Plugin validation/hosting: `core/plugins/host.py`, `core/plugins/formats/agent_plugins_v1.py`

External services include user-configured OpenAI, Anthropic, OpenRouter, Ollama/vLLM-compatible, and other LLM endpoints; MCP servers may use stdio, SSE, or Streamable HTTP.

#### Client and transport boundaries
The App Server exposes a typed local protocol for Desktop; it dispatches operations into the same application services used by CLI. The React Desktop renders projected sessions, workbench data, approvals, management, and automation interfaces; Tauri manages the Python sidecar.
- Protocol codec/models/method dispatch: `app_server/protocol/codec.py`, `app_server/protocol/models.py`, `app_server/dispatcher.py`
- Desktop RPC client/generated protocol: `desktop/src/rpc/tauriRuntime.ts`, `desktop/src/generated/app-server.ts`
- Workspace and thread UI: `desktop/src/app/useWorkspaceController.ts`, `desktop/src/features/thread/ThreadConversation.tsx`
- Sidecar lifecycle: `desktop/src-tauri/src/sidecar.rs`, `desktop/src-tauri/src/lib.rs`

#### Specialized Paper2Code workflows
The original research-oriented pipeline remains a separate orchestration layer for document/paper ingestion, requirements analysis, planning, reference/code indexing, implementation, and review/verification. It reuses LLM and tool infrastructure but preserves specialist workflow stages.
- Orchestration and workflow context: `workflows/agent_orchestration_engine.py`, `workflows/workflow_context.py`
- Planning/review runtime: `workflows/planning_runtime.py`, `workflows/plan_review_runtime.py`
- Document/code implementation agents: `workflows/agents/document_segmentation_agent.py`, `workflows/agents/code_implementation_agent.py`

Main entry points: [`core/agent_runtime/runner.py`](https://github.com/hkuds/deepcode/blob/main/core/agent_runtime/runner.py) (Agent runner), [`core/application/application.py`](https://github.com/hkuds/deepcode/blob/main/core/application/application.py) (Application lifecycle), [`core/application/execution_coordinator.py`](https://github.com/hkuds/deepcode/blob/main/core/application/execution_coordinator.py) (Execution coordinator), [`workflows/agent_orchestration_engine.py`](https://github.com/hkuds/deepcode/blob/main/workflows/agent_orchestration_engine.py) (Paper2Code orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client Interfaces"]
  node_cli["CLI and TUI<br/>Python interface<br/>[app.py]"]
  node_desktop["Desktop UI<br/>React frontend<br/>[main.tsx]"]
  node_tauri["Tauri host<br/>native host<br/>[sidecar.rs]"]
  node_app_server["App Server<br/>local protocol server<br/>[server.py]"]
end

subgraph group_application["Application Control Plane"]
  node_application_core["Application lifecycle<br/>application service<br/>[application.py]"]
  node_turn_service["Turn admission<br/>turn service<br/>[turn_service.py]"]
  node_execution_coordinator["Execution coordinator<br/>orchestrator"]
  node_domain_policy["Domain policy<br/>domain records"]
end

subgraph group_runtime["Agent Execution"]
  node_agent_runner["Agent runner<br/>agent kernel<br/>[runner.py]"]
  node_goal_runtime["Goal runtime<br/>continuation runtime<br/>[goal_runtime.py]"]
  node_tool_registry["Tool registry and MCP bridge<br/>tool integration<br/>[registry.py]"]
  node_harness{{"Supervised tool harness<br/>safety boundary<br/>[permissions.py]"}}
end

subgraph group_state["Durable State"]
  node_database[("SQLite database<br/>canonical persistence<br/>[database.py]")]
  node_thread_events[("Thread and event repositories<br/>event persistence")]
  node_event_bus["In-process event bus<br/>observability<br/>[bus.py]"]
end

subgraph group_integrations["Models and Extensions"]
  node_providers["Model providers<br/>LLM adapters<br/>[catalog_service.py]"]
  node_skills["Skills runtime<br/>instruction composition<br/>[runtime.py]"]
  node_mcp["MCP runtime<br/>external tools<br/>[runtime.py]"]
  node_plugins["Plugin host<br/>extension host<br/>[host.py]"]
end

subgraph group_workflows["Paper2Code"]
  node_paper_orchestrator["Paper2Code orchestration<br/>specialist workflow"]
  node_paper_planning["Planning and review<br/>workflow runtime"]
  node_paper_implementation["Code implementation agent<br/>workflow agent"]
end

node_cli -->|"uses"| node_application_core
node_desktop -->|"runs through"| node_tauri
node_tauri -->|"launches sidecar"| node_app_server
node_desktop -->|"typed local RPC"| node_app_server
node_app_server -->|"dispatches operations"| node_application_core
node_application_core -->|"routes turns"| node_turn_service
node_turn_service -->|"applies policy"| node_domain_policy
node_turn_service -->|"admits work"| node_execution_coordinator
node_execution_coordinator -->|"executes turns"| node_agent_runner
node_agent_runner -->|"continues goals"| node_goal_runtime
node_agent_runner -->|"selects tools"| node_tool_registry
node_tool_registry -->|"executes native tools"| node_harness
node_tool_registry -->|"bridges external tools"| node_mcp
node_agent_runner -->|"requests inference"| node_providers
node_agent_runner -->|"composes skills"| node_skills
node_application_core -->|"hosts extensions"| node_plugins
node_application_core -->|"persists canonical state"| node_database
node_execution_coordinator -->|"records execution events"| node_thread_events
node_thread_events -->|"stores in"| node_database
node_execution_coordinator -->|"publishes events"| node_event_bus
node_paper_orchestrator -->|"plans and reviews"| node_paper_planning
node_paper_planning -->|"drives implementation"| node_paper_implementation
node_paper_orchestrator -.->|"reuses agent runtime"| node_agent_runner
node_paper_orchestrator -->|"persists workflow state"| node_database

click node_cli "https://github.com/hkuds/deepcode/blob/main/cli/tui/app.py"
click node_desktop "https://github.com/hkuds/deepcode/blob/main/desktop/src/main.tsx"
click node_tauri "https://github.com/hkuds/deepcode/blob/main/desktop/src-tauri/src/sidecar.rs"
click node_app_server "https://github.com/hkuds/deepcode/blob/main/app_server/server.py"
click node_application_core "https://github.com/hkuds/deepcode/blob/main/core/application/application.py"
click node_turn_service "https://github.com/hkuds/deepcode/blob/main/core/application/turn_service.py"
click node_execution_coordinator "https://github.com/hkuds/deepcode/blob/main/core/application/execution_coordinator.py"
click node_domain_policy "https://github.com/hkuds/deepcode/blob/main/core/domain/execution_security.py"
click node_agent_runner "https://github.com/hkuds/deepcode/blob/main/core/agent_runtime/runner.py"
click node_goal_runtime "https://github.com/hkuds/deepcode/blob/main/core/agent_runtime/goal_runtime.py"
click node_tool_registry "https://github.com/hkuds/deepcode/blob/main/core/agent_runtime/tools/registry.py"
click node_harness "https://github.com/hkuds/deepcode/blob/main/core/harness/permissions.py"
click node_database "https://github.com/hkuds/deepcode/blob/main/core/persistence/database.py"
click node_thread_events "https://github.com/hkuds/deepcode/blob/main/core/persistence/event_repository.py"
click node_event_bus "https://github.com/hkuds/deepcode/blob/main/core/observability/bus.py"
click node_providers "https://github.com/hkuds/deepcode/blob/main/core/providers/catalog_service.py"
click node_skills "https://github.com/hkuds/deepcode/blob/main/core/skills/runtime.py"
click node_mcp "https://github.com/hkuds/deepcode/blob/main/core/mcp/runtime.py"
click node_plugins "https://github.com/hkuds/deepcode/blob/main/core/plugins/host.py"
click node_paper_orchestrator "https://github.com/hkuds/deepcode/blob/main/workflows/agent_orchestration_engine.py"
click node_paper_planning "https://github.com/hkuds/deepcode/blob/main/workflows/planning_runtime.py"
click node_paper_implementation "https://github.com/hkuds/deepcode/blob/main/workflows/agents/code_implementation_agent.py"

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_cli,node_desktop,node_tauri,node_app_server toneBlue
class node_application_core,node_turn_service,node_execution_coordinator,node_domain_policy toneAmber
class node_agent_runner,node_goal_runtime,node_tool_registry,node_harness toneMint
class node_database,node_thread_events,node_event_bus toneRose
class node_providers,node_skills,node_mcp,node_plugins toneIndigo
class node_paper_orchestrator,node_paper_planning,node_paper_implementation toneTeal
```

## Components

### Client Interfaces

- [CLI and TUI](https://github.com/hkuds/deepcode/blob/main/cli/tui/app.py): Python interface · `cli/tui/app.py`
- [Desktop UI](https://github.com/hkuds/deepcode/blob/main/desktop/src/main.tsx): React frontend · `desktop/src/main.tsx`
- [Tauri host](https://github.com/hkuds/deepcode/blob/main/desktop/src-tauri/src/sidecar.rs): native host · Owns the Python sidecar lifecycle. · `desktop/src-tauri/src/sidecar.rs`
- [App Server](https://github.com/hkuds/deepcode/blob/main/app_server/server.py): local protocol server · Dispatches Desktop operations to shared application services. · `app_server/server.py`

### Application Control Plane

- [Application lifecycle](https://github.com/hkuds/deepcode/blob/main/core/application/application.py): application service · Composes durable work services and session runtime. · `core/application/application.py`
- [Turn admission](https://github.com/hkuds/deepcode/blob/main/core/application/turn_service.py): turn service · Freezes execution/security policy before routing work. · `core/application/turn_service.py`
- [Execution coordinator](https://github.com/hkuds/deepcode/blob/main/core/application/execution_coordinator.py): orchestrator · `core/application/execution_coordinator.py`
- [Domain policy](https://github.com/hkuds/deepcode/blob/main/core/domain/execution_security.py): domain records · Defines threads, turns, and execution security inputs. · `core/domain/execution_security.py`

### Agent Execution

- [Agent runner](https://github.com/hkuds/deepcode/blob/main/core/agent_runtime/runner.py): agent kernel · Resolves context, tools, model calls, pruning, and repeat protection. · `core/agent_runtime/runner.py`
- [Goal runtime](https://github.com/hkuds/deepcode/blob/main/core/agent_runtime/goal_runtime.py): continuation runtime · Continues durable multi-turn Goals. · `core/agent_runtime/goal_runtime.py`
- [Tool registry and MCP bridge](https://github.com/hkuds/deepcode/blob/main/core/agent_runtime/tools/registry.py): tool integration · `core/agent_runtime/tools/registry.py`
- [Supervised tool harness](https://github.com/hkuds/deepcode/blob/main/core/harness/permissions.py): safety boundary · Enforces permissions and sandboxing for local capabilities. · `core/harness/permissions.py`

### Durable State

- [SQLite database](https://github.com/hkuds/deepcode/blob/main/core/persistence/database.py): canonical persistence · Stores projects, threads, events, executions, workflows, automations, and leases. · `core/persistence/database.py`
- [Thread and event repositories](https://github.com/hkuds/deepcode/blob/main/core/persistence/event_repository.py): event persistence · `core/persistence/event_repository.py`
- [In-process event bus](https://github.com/hkuds/deepcode/blob/main/core/observability/bus.py): observability · `core/observability/bus.py`

### Models and Extensions

- [Model providers](https://github.com/hkuds/deepcode/blob/main/core/providers/catalog_service.py): LLM adapters · Routes inference while keeping credentials private. · `core/providers/catalog_service.py`
- [Skills runtime](https://github.com/hkuds/deepcode/blob/main/core/skills/runtime.py): instruction composition · Supplies bounded instructions and capabilities. · `core/skills/runtime.py`
- [MCP runtime](https://github.com/hkuds/deepcode/blob/main/core/mcp/runtime.py): external tools · Manages external tool-server connections under narrowed policy. · `core/mcp/runtime.py`
- [Plugin host](https://github.com/hkuds/deepcode/blob/main/core/plugins/host.py): extension host · `core/plugins/host.py`

### Paper2Code

- [Paper2Code orchestration](https://github.com/hkuds/deepcode/blob/main/workflows/agent_orchestration_engine.py): specialist workflow · Coordinates document-to-code workflow stages. · `workflows/agent_orchestration_engine.py`
- [Planning and review](https://github.com/hkuds/deepcode/blob/main/workflows/planning_runtime.py): workflow runtime · `workflows/planning_runtime.py`
- [Code implementation agent](https://github.com/hkuds/deepcode/blob/main/workflows/agents/code_implementation_agent.py): workflow agent · `workflows/agents/code_implementation_agent.py`

## Connections

- CLI and TUI → Application lifecycle: uses
- Desktop UI → Tauri host: runs through
- Tauri host → App Server: launches sidecar
- Desktop UI → App Server: typed local RPC
- App Server → Application lifecycle: dispatches operations
- Application lifecycle → Turn admission: routes turns
- Turn admission → Domain policy: applies policy
- Turn admission → Execution coordinator: admits work
- Execution coordinator → Agent runner: executes turns
- Agent runner → Goal runtime: continues goals
- Agent runner → Tool registry and MCP bridge: selects tools
- Tool registry and MCP bridge → Supervised tool harness: executes native tools
- Tool registry and MCP bridge → MCP runtime: bridges external tools
- Agent runner → Model providers: requests inference
- Agent runner → Skills runtime: composes skills
- Application lifecycle → Plugin host: hosts extensions
- Application lifecycle → SQLite database: persists canonical state
- Execution coordinator → Thread and event repositories: records execution events
- Thread and event repositories → SQLite database: stores in
- Execution coordinator → In-process event bus: publishes events
- Paper2Code orchestration → Planning and review: plans and reviews
- Planning and review → Code implementation agent: drives implementation
- Paper2Code orchestration → Agent runner: reuses agent runtime
- Paper2Code orchestration → SQLite database: persists workflow state
