# 19h/ratio architecture

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

- Interactive diagram: https://gitdiagram.com/19h/ratio
- Repository: https://github.com/19h/ratio

## Overview

Ratio is a browser- or terminal-driven team of coding agents that plans, executes, reviews, and records repository changes. The main workflow starts with a user request, proceeds through team onboarding and a frozen task plan, dispatches workers through model/tool interactions, then verifies and approves changes for publication. The graph also includes its journal, staged workspaces, control interface, and key extension capabilities. Edges use README statements and source-index references; unsampled subsystem details are kept at directory level.

Main entry points: [`crates/ratio-engine/src/orchestrator.rs`](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator.rs) (Run orchestrator), [`crates/ratio-engine/src/tools.rs`](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools.rs) (Agent tools), [`crates/ratio/src/web.rs`](https://github.com/19h/ratio/blob/master/crates/ratio/src/web.rs) (Web server), [`crates/ratio/src/ui.rs`](https://github.com/19h/ratio/blob/master/crates/ratio/src/ui.rs) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_dashboard["Web dashboard<br/>[dashboard.js]"]
  node_web["Web server<br/>[web.rs]"]
  node_terminal["Terminal UI<br/>[ui.rs]"]
  node_control["Run control<br/>[control.rs]"]
end

subgraph group_coordination["Planning and coordination"]
  node_config["Configuration<br/>[config.rs]"]
  node_orchestrator["Run orchestrator<br/>[orchestrator.rs]"]
  node_onboarding["Team onboarding<br/>[onboarding.rs]"]
  node_triage["Triage<br/>[triage.rs]"]
  node_taskgraph["Task graph<br/>[plan.rs]"]
end

subgraph group_execution["Agent execution"]
  node_modelapi["Model API<br/>[api.rs]"]
  node_context["Agent context<br/>[context.rs]"]
  node_tools["Agent tools<br/>[tools.rs]"]
  node_search["Workspace search<br/>[search.rs]"]
  node_mcp["MCP extensions<br/>[mcp.rs]"]
  node_skills["Local skills<br/>[skills.rs]"]
  node_verify["Verification<br/>[orchestrator.rs]"]
end

subgraph group_records["Workspace and records"]
  node_session["Run session<br/>[session.rs]"]
  node_staging["Staged workspace<br/>[staging.rs]"]
  node_journal[("SQLite journal<br/>[journal.rs]")]
  node_budget["Usage budgets<br/>[budget.rs]"]
end

node_user(("User"))
node_provider["OpenAI-compatible provider"]

node_user -->|"describes goal"| node_dashboard
node_dashboard -->|"uses dashboard"| node_web
node_user -.->|"starts run"| node_terminal
node_terminal -->|"runs orchestration"| node_orchestrator
node_web -.->|"starts runs"| node_orchestrator
node_web -->|"serves interface"| node_dashboard
node_terminal -->|"binds controls"| node_control
node_control -.->|"steers run"| node_orchestrator
node_config -.->|"configures run"| node_orchestrator
node_orchestrator -->|"admits workers"| node_onboarding
node_orchestrator -->|"defers triage"| node_triage
node_orchestrator -.->|"dispatches dependencies"| node_taskgraph
node_orchestrator -->|"requests completions"| node_modelapi
node_modelapi -->|"sends requests"| node_provider
node_orchestrator -->|"uses dialogue"| node_context
node_orchestrator -->|"dispatches calls"| node_tools
node_tools -->|"offers search"| node_search
node_tools -->|"dispatches MCP"| node_mcp
node_tools -->|"dispatches skills"| node_skills
node_orchestrator -->|"runs verification"| node_verify
node_orchestrator -.->|"updates progress"| node_session
node_orchestrator -.->|"stages changes"| node_staging
node_orchestrator -.->|"records activity"| node_journal
node_orchestrator -.->|"enforces limits"| node_budget
node_session -.->|"persists run state"| node_journal
node_staging -.->|"verifies candidate"| node_verify

click node_dashboard "https://github.com/19h/ratio/blob/master/crates/ratio/src/web/dashboard.js"
click node_web "https://github.com/19h/ratio/blob/master/crates/ratio/src/web.rs"
click node_terminal "https://github.com/19h/ratio/blob/master/crates/ratio/src/ui.rs"
click node_control "https://github.com/19h/ratio/blob/master/crates/ratio/src/control.rs"
click node_config "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/config.rs"
click node_orchestrator "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator.rs"
click node_onboarding "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator/onboarding.rs"
click node_triage "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator/triage.rs"
click node_taskgraph "https://github.com/19h/ratio/blob/master/crates/ratio-protocol/src/plan.rs"
click node_modelapi "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/api.rs"
click node_context "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/context.rs"
click node_tools "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools.rs"
click node_search "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools/search.rs"
click node_mcp "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools/mcp.rs"
click node_skills "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools/skills.rs"
click node_verify "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator.rs"
click node_session "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/session.rs"
click node_staging "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/staging.rs"
click node_journal "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/journal.rs"
click node_budget "https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/budget.rs"

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_dashboard,node_web,node_terminal,node_control,node_user toneBlue
class node_config,node_orchestrator,node_onboarding,node_triage,node_taskgraph toneAmber
class node_modelapi,node_context,node_tools,node_search,node_mcp,node_skills,node_verify toneMint
class node_session,node_staging,node_journal,node_budget toneRose
class node_provider toneIndigo
```

## Components

### User interfaces

- [Web dashboard](https://github.com/19h/ratio/blob/master/crates/ratio/src/web/dashboard.js): `crates/ratio/src/web/dashboard.js`
- [Web server](https://github.com/19h/ratio/blob/master/crates/ratio/src/web.rs): `crates/ratio/src/web.rs`
- [Terminal UI](https://github.com/19h/ratio/blob/master/crates/ratio/src/ui.rs): `crates/ratio/src/ui.rs`
- [Run control](https://github.com/19h/ratio/blob/master/crates/ratio/src/control.rs): `crates/ratio/src/control.rs`

### Planning and coordination

- [Configuration](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/config.rs): `crates/ratio-engine/src/config.rs`
- [Run orchestrator](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator.rs): `crates/ratio-engine/src/orchestrator.rs`
- [Team onboarding](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator/onboarding.rs): `crates/ratio-engine/src/orchestrator/onboarding.rs`
- [Triage](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator/triage.rs): `crates/ratio-engine/src/orchestrator/triage.rs`
- [Task graph](https://github.com/19h/ratio/blob/master/crates/ratio-protocol/src/plan.rs): `crates/ratio-protocol/src/plan.rs`

### Agent execution

- [Model API](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/api.rs): `crates/ratio-engine/src/api.rs`
- [Agent context](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/context.rs): `crates/ratio-engine/src/context.rs`
- [Agent tools](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools.rs): `crates/ratio-engine/src/tools.rs`
- [Workspace search](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools/search.rs): `crates/ratio-engine/src/tools/search.rs`
- [MCP extensions](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools/mcp.rs): `crates/ratio-engine/src/tools/mcp.rs`
- [Local skills](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/tools/skills.rs): `crates/ratio-engine/src/tools/skills.rs`
- [Verification](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/orchestrator.rs): `crates/ratio-engine/src/orchestrator.rs`

### Workspace and records

- [Run session](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/session.rs): `crates/ratio-engine/src/session.rs`
- [Staged workspace](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/staging.rs): `crates/ratio-engine/src/staging.rs`
- [SQLite journal](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/journal.rs): `crates/ratio-engine/src/journal.rs`
- [Usage budgets](https://github.com/19h/ratio/blob/master/crates/ratio-engine/src/budget.rs): `crates/ratio-engine/src/budget.rs`

### Other components

- **User**
- **OpenAI-compatible provider**

## Connections

- User → Web dashboard: describes goal
- Web dashboard → Web server: uses dashboard
- User → Terminal UI: starts run
- Terminal UI → Run orchestrator: runs orchestration (evidence: `crates/ratio/src/ui.rs`)
- Web server → Run orchestrator: starts runs
- Web server → Web dashboard: serves interface (evidence: `crates/ratio/src/web.rs`)
- Terminal UI → Run control: binds controls (evidence: `crates/ratio/src/ui.rs`)
- Run control → Run orchestrator: steers run
- Configuration → Run orchestrator: configures run
- Run orchestrator → Team onboarding: admits workers (evidence: `crates/ratio-engine/src/orchestrator.rs`)
- Run orchestrator → Triage: defers triage (evidence: `crates/ratio-engine/src/orchestrator.rs`)
- Run orchestrator → Task graph: dispatches dependencies
- Run orchestrator → Model API: requests completions (evidence: `crates/ratio-engine/src/orchestrator.rs`)
- Model API → OpenAI-compatible provider: sends requests (evidence: `crates/ratio-engine/src/api.rs`)
- Run orchestrator → Agent context: uses dialogue (evidence: `crates/ratio-engine/src/context.rs`)
- Run orchestrator → Agent tools: dispatches calls (evidence: `crates/ratio-engine/src/orchestrator.rs`)
- Agent tools → Workspace search: offers search (evidence: `crates/ratio-engine/src/tools.rs`)
- Agent tools → MCP extensions: dispatches MCP (evidence: `crates/ratio-engine/src/tools.rs`)
- Agent tools → Local skills: dispatches skills (evidence: `crates/ratio-engine/src/tools.rs`)
- Run orchestrator → Verification: runs verification (evidence: `crates/ratio-engine/src/orchestrator.rs`)
- Run orchestrator → Run session: updates progress
- Run orchestrator → Staged workspace: stages changes
- Run orchestrator → SQLite journal: records activity
- Run orchestrator → Usage budgets: enforces limits
- Run session → SQLite journal: persists run state
- Staged workspace → Verification: verifies candidate
