# reedsha/aleth architecture

> Architecture diagram of the GitHub repository reedsha/aleth, 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/reedsha/aleth
- Repository: https://github.com/reedsha/aleth

## Overview

Aleth is a local, single-process AI execution engine with a browser UI and typed API. A user submits a task; the engine routes it through planning and agent execution, runs code in disposable containers against a shadow workspace, and presents changes for approval before merge. Retrieval, structured plan parsing, and persistent run state support that workflow; the README also documents boot checks, migrations, maintenance, and a loopback-only server. Some subsystem links are dashed because their caller-to-callee wiring was not shown in the sampled source.

Main entry points: [`orchestration/workflow/actions_impl.py`](https://github.com/reedsha/aleth/blob/master/orchestration/workflow/actions_impl.py) (Workflow actions), [`orchestration/retriever.py`](https://github.com/reedsha/aleth/blob/master/orchestration/retriever.py) (Hybrid retriever), [`orchestration/workflow/planner.py`](https://github.com/reedsha/aleth/blob/master/orchestration/workflow/planner.py) (Task planner), [`api/server.py`](https://github.com/reedsha/aleth/blob/master/api/server.py) (Loopback HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_browser["Browser workbench<br/>[workbench.js]"]
  node_ui_state["UI state and events<br/>[store.js]"]
  node_ui_api["API client<br/>[api-client.js]"]
  node_ui_stream["Run stream and views<br/>[stream.js]"]
end

subgraph group_service["HTTP service"]
  node_http["Loopback HTTP server<br/>[server.py]"]
  node_gateway["API gateway<br/>[gateway.py]"]
  node_intents["Intent operations<br/>[intents.py]"]
  node_boot["Boot and lifecycle<br/>[main.py]"]
end

subgraph group_orchestration["Planning and agents"]
  node_architect["Architect and Coders<br/>[architect.py]"]
  node_laya["Laya routing<br/>[laya.py]"]
  node_workflow["Workflow actions<br/>[actions_impl.py]"]
  node_planner["Task planner<br/>[planner.py]"]
  node_worker["Workflow worker<br/>[worker.py]"]
  node_retriever["Hybrid retriever<br/>[retriever.py]"]
  node_plan_parser["Plan parser<br/>[parser.rs]"]
end

subgraph group_execution["Execution and workspace"]
  node_sandbox["Container sandbox<br/>[docker_sandbox.py]"]
  node_workspace["Shadow workspace<br/>[workspace.py]"]
  node_staging["Change staging<br/>[staging.py]"]
end

subgraph group_state["State and knowledge"]
  node_state_db[("SQLite state and ledger<br/>[db.py]")]
  node_connection["Database connections<br/>[connection.py]"]
  node_graph["Knowledge graph<br/>[graph_engine.py]"]
  node_vectors[("Vector store<br/>[vector_store.py]")]
  node_semantic["Semantic index<br/>[semantic_index.py]"]
end

node_user(("User"))
node_docker{{"Docker daemon"}}

node_user -->|"submits task"| node_browser
node_browser -.->|"updates state"| node_ui_state
node_browser -.->|"sends requests"| node_ui_api
node_ui_api -.->|"calls API"| node_http
node_http -->|"dispatches requests"| node_gateway
node_gateway -->|"routes intents"| node_intents
node_intents -.->|"starts work"| node_workflow
node_workflow -->|"classifies tasks"| node_laya
node_workflow -->|"plans tasks"| node_planner
node_planner -->|"retrieves context"| node_retriever
node_retriever -->|"embeds query"| node_semantic
node_retriever -->|"searches vectors"| node_vectors
node_retriever -->|"traverses graph"| node_graph
node_planner -.->|"parses plans"| node_plan_parser
node_planner -->|"delegates execution"| node_worker
node_worker -.->|"runs workflow"| node_workflow
node_workflow -->|"invokes agents"| node_architect
node_workflow -->|"reads workspace"| node_workspace
node_workflow -.->|"executes code"| node_sandbox
node_sandbox -->|"runs containers"| node_docker
node_sandbox -->|"mounts shadow"| node_workspace
node_workflow -.->|"stages changes"| node_staging
node_user -->|"approves merge"| node_staging
node_workflow -->|"opens state"| node_connection
node_connection -->|"connects SQLite"| node_state_db
node_graph -->|"queries tables"| node_state_db
node_retriever -->|"uses connection"| node_connection
node_retriever -.->|"returns context"| node_ui_stream
node_http -.->|"streams run events"| node_ui_stream
node_boot -->|"migrates schema"| node_state_db
node_boot -.->|"starts server"| node_http

click node_browser "https://github.com/reedsha/aleth/blob/master/ui/js/workbench.js"
click node_ui_state "https://github.com/reedsha/aleth/blob/master/ui/js/store.js"
click node_ui_api "https://github.com/reedsha/aleth/blob/master/ui/js/api-client.js"
click node_ui_stream "https://github.com/reedsha/aleth/blob/master/ui/js/stream.js"
click node_http "https://github.com/reedsha/aleth/blob/master/api/server.py"
click node_gateway "https://github.com/reedsha/aleth/blob/master/api/gateway.py"
click node_intents "https://github.com/reedsha/aleth/blob/master/api/intents.py"
click node_architect "https://github.com/reedsha/aleth/blob/master/agents/architect.py"
click node_laya "https://github.com/reedsha/aleth/blob/master/agents/laya.py"
click node_workflow "https://github.com/reedsha/aleth/blob/master/orchestration/workflow/actions_impl.py"
click node_planner "https://github.com/reedsha/aleth/blob/master/orchestration/workflow/planner.py"
click node_worker "https://github.com/reedsha/aleth/blob/master/orchestration/worker.py"
click node_retriever "https://github.com/reedsha/aleth/blob/master/orchestration/retriever.py"
click node_plan_parser "https://github.com/reedsha/aleth/blob/master/crates/deepagents_core/src/parser.rs"
click node_sandbox "https://github.com/reedsha/aleth/blob/master/tools/docker_sandbox.py"
click node_workspace "https://github.com/reedsha/aleth/blob/master/tools/workspace.py"
click node_staging "https://github.com/reedsha/aleth/blob/master/tools/staging.py"
click node_state_db "https://github.com/reedsha/aleth/blob/master/storage/db.py"
click node_connection "https://github.com/reedsha/aleth/blob/master/storage/connection.py"
click node_graph "https://github.com/reedsha/aleth/blob/master/storage/graph_engine.py"
click node_vectors "https://github.com/reedsha/aleth/blob/master/storage/vector_store.py"
click node_semantic "https://github.com/reedsha/aleth/blob/master/tools/semantic_index.py"
click node_boot "https://github.com/reedsha/aleth/blob/master/main.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_browser,node_ui_state,node_ui_api,node_ui_stream,node_user toneBlue
class node_http,node_gateway,node_intents,node_boot toneAmber
class node_architect,node_laya,node_workflow,node_planner,node_worker,node_retriever,node_plan_parser toneMint
class node_sandbox,node_workspace,node_staging toneRose
class node_state_db,node_connection,node_graph,node_vectors,node_semantic,node_docker toneIndigo
```

## Components

### User interface

- [Browser workbench](https://github.com/reedsha/aleth/blob/master/ui/js/workbench.js): `ui/js/workbench.js`
- [UI state and events](https://github.com/reedsha/aleth/blob/master/ui/js/store.js): `ui/js/store.js`
- [API client](https://github.com/reedsha/aleth/blob/master/ui/js/api-client.js): `ui/js/api-client.js`
- [Run stream and views](https://github.com/reedsha/aleth/blob/master/ui/js/stream.js): `ui/js/stream.js`

### HTTP service

- [Loopback HTTP server](https://github.com/reedsha/aleth/blob/master/api/server.py): `api/server.py`
- [API gateway](https://github.com/reedsha/aleth/blob/master/api/gateway.py): `api/gateway.py`
- [Intent operations](https://github.com/reedsha/aleth/blob/master/api/intents.py): `api/intents.py`
- [Boot and lifecycle](https://github.com/reedsha/aleth/blob/master/main.py): `main.py`

### Planning and agents

- [Architect and Coders](https://github.com/reedsha/aleth/blob/master/agents/architect.py): `agents/architect.py`
- [Laya routing](https://github.com/reedsha/aleth/blob/master/agents/laya.py): `agents/laya.py`
- [Workflow actions](https://github.com/reedsha/aleth/blob/master/orchestration/workflow/actions_impl.py): `orchestration/workflow/actions_impl.py`
- [Task planner](https://github.com/reedsha/aleth/blob/master/orchestration/workflow/planner.py): `orchestration/workflow/planner.py`
- [Workflow worker](https://github.com/reedsha/aleth/blob/master/orchestration/worker.py): `orchestration/worker.py`
- [Hybrid retriever](https://github.com/reedsha/aleth/blob/master/orchestration/retriever.py): `orchestration/retriever.py`
- [Plan parser](https://github.com/reedsha/aleth/blob/master/crates/deepagents_core/src/parser.rs): `crates/deepagents_core/src/parser.rs`

### Execution and workspace

- [Container sandbox](https://github.com/reedsha/aleth/blob/master/tools/docker_sandbox.py): `tools/docker_sandbox.py`
- [Shadow workspace](https://github.com/reedsha/aleth/blob/master/tools/workspace.py): `tools/workspace.py`
- [Change staging](https://github.com/reedsha/aleth/blob/master/tools/staging.py): `tools/staging.py`

### State and knowledge

- [SQLite state and ledger](https://github.com/reedsha/aleth/blob/master/storage/db.py): `storage/db.py`
- [Database connections](https://github.com/reedsha/aleth/blob/master/storage/connection.py): `storage/connection.py`
- [Knowledge graph](https://github.com/reedsha/aleth/blob/master/storage/graph_engine.py): `storage/graph_engine.py`
- [Vector store](https://github.com/reedsha/aleth/blob/master/storage/vector_store.py): `storage/vector_store.py`
- [Semantic index](https://github.com/reedsha/aleth/blob/master/tools/semantic_index.py): `tools/semantic_index.py`

### Other components

- **User**
- **Docker daemon**

## Connections

- User → Browser workbench: submits task
- Browser workbench → UI state and events: updates state
- Browser workbench → API client: sends requests
- API client → Loopback HTTP server: calls API
- Loopback HTTP server → API gateway: dispatches requests (evidence: `api/server.py`)
- API gateway → Intent operations: routes intents (evidence: `api/server.py`)
- Intent operations → Workflow actions: starts work
- Workflow actions → Laya routing: classifies tasks (evidence: `orchestration/workflow/actions_impl.py`)
- Workflow actions → Task planner: plans tasks (evidence: `orchestration/workflow/actions_impl.py`)
- Task planner → Hybrid retriever: retrieves context (evidence: `orchestration/workflow/planner.py`)
- Hybrid retriever → Semantic index: embeds query (evidence: `orchestration/retriever.py`)
- Hybrid retriever → Vector store: searches vectors (evidence: `orchestration/retriever.py`)
- Hybrid retriever → Knowledge graph: traverses graph (evidence: `orchestration/retriever.py`)
- Task planner → Plan parser: parses plans
- Task planner → Workflow worker: delegates execution (evidence: `orchestration/workflow/planner.py`)
- Workflow worker → Workflow actions: runs workflow
- Workflow actions → Architect and Coders: invokes agents (evidence: `orchestration/workflow/actions_impl.py`)
- Workflow actions → Shadow workspace: reads workspace (evidence: `orchestration/workflow/actions_impl.py`)
- Workflow actions → Container sandbox: executes code
- Container sandbox → Docker daemon: runs containers
- Container sandbox → Shadow workspace: mounts shadow
- Workflow actions → Change staging: stages changes
- User → Change staging: approves merge
- Workflow actions → Database connections: opens state (evidence: `orchestration/workflow/actions_impl.py`)
- Database connections → SQLite state and ledger: connects SQLite (evidence: `storage/connection.py`)
- Knowledge graph → SQLite state and ledger: queries tables (evidence: `storage/graph_engine.py`)
- Hybrid retriever → Database connections: uses connection (evidence: `orchestration/retriever.py`)
- Hybrid retriever → Run stream and views: returns context
- Loopback HTTP server → Run stream and views: streams run events
- Boot and lifecycle → SQLite state and ledger: migrates schema (evidence: `main.py`)
- Boot and lifecycle → Loopback HTTP server: starts server
