# xiaotianfotos/homerail architecture

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

- Interactive diagram: https://gitdiagram.com/xiaotianfotos/homerail
- Repository: https://github.com/xiaotianfotos/homerail

## Overview

HomeRail is a self-hosted agent runtime that turns voice or text requests into auditable, replayable DAG workflows. Its principal path is user request → CLI or Agent UI → Manager orchestration → per-node Worker execution → inspectable run state and evidence. The README documents the service topology and product capabilities; source excerpts confirm selected orchestration, persistence, and workspace-preparation calls. Many UI, voice, and route implementations were not sampled, so those relationships are documented at the README level rather than inferred from names.

Main entry points: [`homerail_manager/src/server/routes.ts`](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/server/routes.ts) (Manager API), [`homerail_node/src/control-plane/lifecycle-handler.ts`](https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/control-plane/lifecycle-handler.ts) (Node service), [`homerail_manager/src/persistence/store.ts`](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/persistence/store.ts) (Run state store), [`homerail_cli/src/index.ts`](https://github.com/xiaotianfotos/homerail/blob/main/homerail_cli/src/index.ts) (HomeRail CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_cli["HomeRail CLI<br/>[index.ts]"]
  node_cli_transport["Manager transport<br/>[client.ts]"]
  node_agent_ui["Agent UI<br/>[index.vue]"]
  node_voice_surface["Voice surface"]
  node_generative_ui["Generated interface"]
end

subgraph group_orchestration["DAG orchestration"]
  node_dag_engine["DAG engine<br/>[dag-engine.ts]"]
  node_workflow_graph["Workflow graph<br/>[graph.ts]"]
  node_supervisor["Run supervisor"]
end

subgraph group_execution["Worker execution"]
  node_node_service["Node service"]
  node_workspace["Workspace preparation"]
  node_workspace_inputs["Workspace inputs"]
  node_worker["DAG Worker<br/>[index.ts]"]
  node_worker_agent["Agent turn runner<br/>[turn-controller.ts]"]
  node_plugin_runtime["Plugin runtime"]
end

subgraph group_platform["Runtime platform"]
  node_manager_http["Manager API<br/>[routes.ts]"]
  node_run_store[("Run state store<br/>[store.ts]")]
  node_db[("Manager database<br/>[db.ts]")]
end

node_person(("Home user"))
node_model_endpoint(("Model endpoint"))

node_person -->|"operates"| node_cli
node_person -->|"requests work"| node_agent_ui
node_person -->|"speaks intent"| node_voice_surface
node_cli -->|"issues commands"| node_cli_transport
node_cli_transport -->|"sends API requests"| node_manager_http
node_agent_ui -->|"uses Manager"| node_manager_http
node_voice_surface -.->|"sends voice requests"| node_manager_http
node_manager_http -->|"starts DAG runs"| node_dag_engine
node_dag_engine -->|"uses graph structure"| node_workflow_graph
node_manager_http -.->|"supervises runs"| node_supervisor
node_supervisor -->|"loads run metadata"| node_run_store
node_run_store -->|"reads graph"| node_workflow_graph
node_run_store -->|"uses database"| node_db
node_manager_http -->|"coordinates services"| node_node_service
node_node_service -->|"prepares workspace"| node_workspace
node_node_service -->|"materializes inputs"| node_workspace_inputs
node_node_service -->|"provisions containers"| node_worker
node_worker -.->|"runs agent turns"| node_worker_agent
node_worker_agent -->|"requests model output"| node_model_endpoint
node_manager_http -.->|"serves generated views"| node_generative_ui
node_node_service -.->|"supports plugin execution"| node_plugin_runtime

click node_cli "https://github.com/xiaotianfotos/homerail/blob/main/homerail_cli/src/index.ts"
click node_cli_transport "https://github.com/xiaotianfotos/homerail/blob/main/homerail_cli/src/client.ts"
click node_agent_ui "https://github.com/xiaotianfotos/homerail/blob/main/agent-ui/src/views/agent/index.vue"
click node_voice_surface "https://github.com/xiaotianfotos/homerail/blob/main/agent-ui/src/components/agent/AgentVoiceCockpit.vue"
click node_manager_http "https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/server/routes.ts"
click node_dag_engine "https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/orchestration/dag-engine.ts"
click node_workflow_graph "https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/orchestration/graph.ts"
click node_supervisor "https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/runtime/dag-manager-supervisor.ts"
click node_run_store "https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/persistence/store.ts"
click node_db "https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/persistence/db.ts"
click node_node_service "https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/control-plane/lifecycle-handler.ts"
click node_workspace "https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/storage/workspace-prepare.ts"
click node_workspace_inputs "https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/storage/workspace-inputs.ts"
click node_worker "https://github.com/xiaotianfotos/homerail/blob/main/homerail_worker/src/index.ts"
click node_worker_agent "https://github.com/xiaotianfotos/homerail/blob/main/homerail_worker/src/agent/turn-controller.ts"
click node_generative_ui "https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/generative-ui/surface-composer.ts"
click node_plugin_runtime "https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/runtime/plugin-runtime-service.ts"

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_cli_transport,node_agent_ui,node_voice_surface,node_generative_ui,node_person toneBlue
class node_dag_engine,node_workflow_graph,node_supervisor toneAmber
class node_node_service,node_workspace,node_workspace_inputs,node_worker,node_worker_agent,node_plugin_runtime toneMint
class node_manager_http,node_run_store,node_db toneRose
class node_model_endpoint toneIndigo
```

## Components

### User interaction

- [HomeRail CLI](https://github.com/xiaotianfotos/homerail/blob/main/homerail_cli/src/index.ts): `homerail_cli/src/index.ts`
- [Manager transport](https://github.com/xiaotianfotos/homerail/blob/main/homerail_cli/src/client.ts): `homerail_cli/src/client.ts`
- [Agent UI](https://github.com/xiaotianfotos/homerail/blob/main/agent-ui/src/views/agent/index.vue): `agent-ui/src/views/agent/index.vue`
- [Voice surface](https://github.com/xiaotianfotos/homerail/blob/main/agent-ui/src/components/agent/AgentVoiceCockpit.vue): `agent-ui/src/components/agent/AgentVoiceCockpit.vue`
- [Generated interface](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/generative-ui/surface-composer.ts): `homerail_manager/src/generative-ui/surface-composer.ts`

### DAG orchestration

- [DAG engine](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/orchestration/dag-engine.ts): `homerail_manager/src/orchestration/dag-engine.ts`
- [Workflow graph](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/orchestration/graph.ts): `homerail_manager/src/orchestration/graph.ts`
- [Run supervisor](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/runtime/dag-manager-supervisor.ts): `homerail_manager/src/runtime/dag-manager-supervisor.ts`

### Worker execution

- [Node service](https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/control-plane/lifecycle-handler.ts): `homerail_node/src/control-plane/lifecycle-handler.ts`
- [Workspace preparation](https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/storage/workspace-prepare.ts): `homerail_node/src/storage/workspace-prepare.ts`
- [Workspace inputs](https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/storage/workspace-inputs.ts): `homerail_node/src/storage/workspace-inputs.ts`
- [DAG Worker](https://github.com/xiaotianfotos/homerail/blob/main/homerail_worker/src/index.ts): `homerail_worker/src/index.ts`
- [Agent turn runner](https://github.com/xiaotianfotos/homerail/blob/main/homerail_worker/src/agent/turn-controller.ts): `homerail_worker/src/agent/turn-controller.ts`
- [Plugin runtime](https://github.com/xiaotianfotos/homerail/blob/main/homerail_node/src/runtime/plugin-runtime-service.ts): `homerail_node/src/runtime/plugin-runtime-service.ts`

### Runtime platform

- [Manager API](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/server/routes.ts): `homerail_manager/src/server/routes.ts`
- [Run state store](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/persistence/store.ts): `homerail_manager/src/persistence/store.ts`
- [Manager database](https://github.com/xiaotianfotos/homerail/blob/main/homerail_manager/src/persistence/db.ts): `homerail_manager/src/persistence/db.ts`

### Other components

- **Home user**
- **Model endpoint**

## Connections

- Home user → HomeRail CLI: operates (evidence: `README.md`)
- Home user → Agent UI: requests work (evidence: `README.md`)
- Home user → Voice surface: speaks intent (evidence: `README.md`)
- HomeRail CLI → Manager transport: issues commands (evidence: `homerail_cli/src/index.ts`)
- Manager transport → Manager API: sends API requests (evidence: `homerail_cli/src/client.ts`)
- Agent UI → Manager API: uses Manager (evidence: `README.md`)
- Voice surface → Manager API: sends voice requests (evidence: `README.md`)
- Manager API → DAG engine: starts DAG runs (evidence: `README.md`)
- DAG engine → Workflow graph: uses graph structure (evidence: `homerail_manager/src/orchestration/dag-engine.ts`)
- Manager API → Run supervisor: supervises runs
- Run supervisor → Run state store: loads run metadata (evidence: `homerail_manager/src/runtime/dag-manager-supervisor.ts`)
- Run state store → Workflow graph: reads graph (evidence: `homerail_manager/src/persistence/store.ts`)
- Run state store → Manager database: uses database (evidence: `homerail_manager/src/persistence/store.ts`)
- Manager API → Node service: coordinates services (evidence: `README.md`)
- Node service → Workspace preparation: prepares workspace (evidence: `homerail_node/src/control-plane/lifecycle-handler.ts`)
- Node service → Workspace inputs: materializes inputs (evidence: `homerail_node/src/control-plane/lifecycle-handler.ts`)
- Node service → DAG Worker: provisions containers (evidence: `README.md`)
- DAG Worker → Agent turn runner: runs agent turns
- Agent turn runner → Model endpoint: requests model output (evidence: `README.md`)
- Manager API → Generated interface: serves generated views (evidence: `README.md`)
- Node service → Plugin runtime: supports plugin execution (evidence: `homerail_node/src/control-plane/lifecycle-handler.ts`)
