# advaith-1212/railwarden architecture

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

- Interactive diagram: https://gitdiagram.com/advaith-1212/railwarden
- Repository: https://github.com/advaith-1212/railwarden

## Overview

RailWarden is a deterministic control plane for multi-agent software work: approved plans become dependency-aware packages, workers implement them in isolated Git worktrees, and validation, review, and integration gates determine completion. The controller coordinates execution; file-backed runtime state and events preserve facts across failures. The README documents the major lifecycle and supporting interfaces. Some subsystem paths and interactions are represented at directory level because their implementation was not excerpted.

Main entry points: [`src/railwarden/engine/controller.py`](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/engine/controller.py) (Execution Controller), [`src/railwarden/cli/main.py`](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/cli/main.py) (CLI), [`src/railwarden/planning/pipeline.py`](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/planning/pipeline.py) (Plan Pipeline), [`src/railwarden/integration/manager.py`](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/integration/manager.py) (Integration Gates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[main.py]"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
  node_kanban["Kanban View<br/>[kanban.py]"]
  node_tmux["tmux Sessions<br/>[session.py]"]
  node_hermes["Hermes Integration<br/>[profile.py]"]
end

subgraph group_planning["Planning and Scheduling"]
  node_planning_pipeline["Plan Pipeline<br/>[pipeline.py]"]
  node_package_dag["Package Scheduler<br/>[classifier.py]"]
  node_config["Project Contracts<br/>[models.py]"]
end

subgraph group_execution["Worker Execution"]
  node_controller["Execution Controller<br/>[controller.py]"]
  node_worktrees["Git Worktrees<br/>[worktrees.py]"]
  node_git["Git Operations<br/>[git.py]"]
  node_supervisor["Process Supervisor<br/>[supervisor.py]"]
  node_providers["Provider Adapters<br/>[adapters.py]"]
end

subgraph group_state["Runtime State"]
  node_tasks[("Task State<br/>[tasks.py]")]
  node_events[("Event Log<br/>[events.py]")]
  node_recovery[("Recovery State<br/>[checkpoints.py]")]
  node_results["Worker Results<br/>[results.py]"]
end

subgraph group_gates["Validation and Integration"]
  node_validation["Mechanical Validation<br/>[package.py]"]
  node_review["Review Gates<br/>[review.py]"]
  node_integration["Integration Gates<br/>[manager.py]"]
end

node_developer(("Developer"))

node_developer -->|"invokes"| node_cli
node_developer -->|"uses tools"| node_mcp
node_cli -->|"controls execution"| node_controller
node_mcp -->|"calls"| node_controller
node_controller -->|"loads plans"| node_planning_pipeline
node_planning_pipeline -->|"builds packages"| node_config
node_planning_pipeline -->|"defines dependencies"| node_package_dag
node_controller -->|"classifies packages"| node_package_dag
node_controller -->|"updates tasks"| node_tasks
node_controller -->|"provisions worktrees"| node_worktrees
node_worktrees -->|"runs Git"| node_git
node_controller -->|"supervises workers"| node_supervisor
node_supervisor -->|"launches adapters"| node_providers
node_controller -->|"normalizes results"| node_results
node_controller -->|"validates packages"| node_validation
node_controller -->|"checks readiness"| node_review
node_controller -->|"records checkpoints"| node_recovery
node_controller -->|"records events"| node_events
node_controller -->|"requests integration"| node_integration
node_integration -->|"merges branches"| node_git
node_integration -->|"runs post-merge checks"| node_validation
node_cli -->|"presents status"| node_dashboard
node_hermes -->|"supports board view"| node_kanban
node_tmux -->|"manages worker panes"| node_supervisor
node_hermes -->|"supervises workflow"| node_controller
node_controller -->|"hands off failures"| node_recovery

click node_cli "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/cli/main.py"
click node_mcp "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/mcp/server.py"
click node_dashboard "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/engine/dashboard.py"
click node_kanban "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/hermes/kanban.py"
click node_planning_pipeline "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/planning/pipeline.py"
click node_package_dag "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/scheduler/classifier.py"
click node_config "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/config/models.py"
click node_controller "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/engine/controller.py"
click node_worktrees "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/provisioning/worktrees.py"
click node_git "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/git.py"
click node_supervisor "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/processes/supervisor.py"
click node_providers "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/providers/adapters.py"
click node_tmux "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/tmux/session.py"
click node_hermes "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/hermes/profile.py"
click node_tasks "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/runtime/tasks.py"
click node_events "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/runtime/events.py"
click node_recovery "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/runtime/checkpoints.py"
click node_results "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/runtime/results.py"
click node_validation "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/validation/package.py"
click node_review "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/validation/review.py"
click node_integration "https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/integration/manager.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_mcp,node_dashboard,node_kanban,node_tmux,node_hermes toneBlue
class node_planning_pipeline,node_package_dag,node_config toneAmber
class node_controller,node_worktrees,node_git,node_supervisor,node_providers toneMint
class node_tasks,node_events,node_recovery,node_results toneRose
class node_validation,node_review,node_integration,node_developer toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/cli/main.py): `src/railwarden/cli/main.py`
- [MCP Server](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/mcp/server.py): `src/railwarden/mcp/server.py`
- [Dashboard](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/engine/dashboard.py): `src/railwarden/engine/dashboard.py`
- [Kanban View](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/hermes/kanban.py): `src/railwarden/hermes/kanban.py`
- [tmux Sessions](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/tmux/session.py): `src/railwarden/tmux/session.py`
- [Hermes Integration](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/hermes/profile.py): `src/railwarden/hermes/profile.py`

### Planning and Scheduling

- [Plan Pipeline](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/planning/pipeline.py): `src/railwarden/planning/pipeline.py`
- [Package Scheduler](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/scheduler/classifier.py): `src/railwarden/scheduler/classifier.py`
- [Project Contracts](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/config/models.py): `src/railwarden/config/models.py`

### Worker Execution

- [Execution Controller](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/engine/controller.py): `src/railwarden/engine/controller.py`
- [Git Worktrees](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/provisioning/worktrees.py): `src/railwarden/provisioning/worktrees.py`
- [Git Operations](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/git.py): `src/railwarden/git.py`
- [Process Supervisor](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/processes/supervisor.py): `src/railwarden/processes/supervisor.py`
- [Provider Adapters](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/providers/adapters.py): `src/railwarden/providers/adapters.py`

### Runtime State

- [Task State](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/runtime/tasks.py): `src/railwarden/runtime/tasks.py`
- [Event Log](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/runtime/events.py): `src/railwarden/runtime/events.py`
- [Recovery State](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/runtime/checkpoints.py): `src/railwarden/runtime/checkpoints.py`
- [Worker Results](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/runtime/results.py): `src/railwarden/runtime/results.py`

### Validation and Integration

- [Mechanical Validation](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/validation/package.py): `src/railwarden/validation/package.py`
- [Review Gates](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/validation/review.py): `src/railwarden/validation/review.py`
- [Integration Gates](https://github.com/advaith-1212/railwarden/blob/main/src/railwarden/integration/manager.py): `src/railwarden/integration/manager.py`

### Other components

- **Developer**

## Connections

- Developer → CLI: invokes (evidence: `README.md`)
- Developer → MCP Server: uses tools (evidence: `README.md`)
- CLI → Execution Controller: controls execution (evidence: `src/railwarden/cli/main.py`)
- MCP Server → Execution Controller: calls (evidence: `src/railwarden/mcp/server.py`)
- Execution Controller → Plan Pipeline: loads plans (evidence: `src/railwarden/engine/controller.py`)
- Plan Pipeline → Project Contracts: builds packages (evidence: `src/railwarden/planning/pipeline.py`)
- Plan Pipeline → Package Scheduler: defines dependencies (evidence: `README.md`)
- Execution Controller → Package Scheduler: classifies packages (evidence: `src/railwarden/engine/controller.py`)
- Execution Controller → Task State: updates tasks (evidence: `src/railwarden/engine/controller.py`)
- Execution Controller → Git Worktrees: provisions worktrees (evidence: `src/railwarden/engine/controller.py`)
- Git Worktrees → Git Operations: runs Git (evidence: `src/railwarden/provisioning/worktrees.py`)
- Execution Controller → Process Supervisor: supervises workers (evidence: `src/railwarden/engine/controller.py`)
- Process Supervisor → Provider Adapters: launches adapters (evidence: `src/railwarden/providers/adapters.py`)
- Execution Controller → Worker Results: normalizes results (evidence: `src/railwarden/engine/controller.py`)
- Execution Controller → Mechanical Validation: validates packages (evidence: `README.md`)
- Execution Controller → Review Gates: checks readiness (evidence: `README.md`)
- Execution Controller → Recovery State: records checkpoints (evidence: `README.md`)
- Execution Controller → Event Log: records events (evidence: `README.md`)
- Execution Controller → Integration Gates: requests integration (evidence: `README.md`)
- Integration Gates → Git Operations: merges branches (evidence: `src/railwarden/integration/manager.py`)
- Integration Gates → Mechanical Validation: runs post-merge checks (evidence: `src/railwarden/integration/manager.py`)
- CLI → Dashboard: presents status (evidence: `src/railwarden/cli/main.py`)
- Hermes Integration → Kanban View: supports board view (evidence: `README.md`)
- tmux Sessions → Process Supervisor: manages worker panes (evidence: `src/railwarden/tmux/session.py`)
- Hermes Integration → Execution Controller: supervises workflow (evidence: `README.md`)
- Execution Controller → Recovery State: hands off failures (evidence: `README.md`)