# otto-rs/otto architecture

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

- Interactive diagram: https://gitdiagram.com/otto-rs/otto
- Repository: https://github.com/otto-rs/otto

## Overview

Otto is a Rust CLI for defining and running Make-like tasks from YAML ottofiles. Its main workflow discovers and parses a configuration, resolves task parameters and dependencies, then schedules task actions and records the run. The README also documents task-graph visualization, task listing, Makefile conversion, run cleanup/history/statistics, an interactive TUI, and upgrades. The sampled code confirms the application’s scheduler and state-completion calls; links between unsampled subsystems are limited to documented capabilities or omitted where ownership is unclear.

Main entry points: [`src/app.rs`](https://github.com/otto-rs/otto/blob/main/src/app.rs) (Application), [`src/executor/scheduler.rs`](https://github.com/otto-rs/otto/blob/main/src/executor/scheduler.rs) (Task scheduler), [`src/cli/parser.rs`](https://github.com/otto-rs/otto/blob/main/src/cli/parser.rs) (CLI parser), [`src/executor/state/manager.rs`](https://github.com/otto-rs/otto/blob/main/src/executor/state/manager.rs) (Run state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI and UI"]
  node_main["CLI entry<br/>[main.rs]"]
  node_app["Application<br/>[app.rs]"]
  node_tui["TUI dashboard<br/>[app.rs]"]
end

subgraph group_configuration["Task configuration"]
  node_parser["CLI parser<br/>[parser.rs]"]
  node_cfg["Config model<br/>[config.rs]"]
  node_resolver["Foreach resolver<br/>[resolver.rs]"]
end

subgraph group_execution["Task execution"]
  node_task["Executor tasks<br/>[task.rs]"]
  node_dag["Dependency graph<br/>[graph.rs]"]
  node_scheduler["Task scheduler<br/>[scheduler.rs]"]
  node_action["Action processor<br/>[action.rs]"]
  node_output["Task output<br/>[output.rs]"]
  node_workspace["Run workspace<br/>[workspace.rs]"]
end

subgraph group_history["Run history"]
  node_state["Run state<br/>[manager.rs]"]
  node_database[("SQLite database<br/>[db.rs]")]
end

subgraph group_commands["Built-in commands"]
  node_makefile["Makefile converter<br/>[converter.rs]"]
  node_graphcmd["Graph command<br/>[graph.rs]"]
  node_tasks["Task listing<br/>[tasks.rs]"]
  node_clean["Clean command<br/>[clean.rs]"]
  node_convert["Convert command<br/>[convert.rs]"]
  node_historycmd["History command<br/>[history.rs]"]
  node_stats["Stats command<br/>[stats.rs]"]
  node_upgrade["Upgrade command<br/>[upgrade.rs]"]
end

node_user(("Engineer"))
node_release(("Release service"))
node_ottofile["Ottofile"]
node_shell["Task processes"]

node_user -->|"invokes"| node_main
node_main -->|"runs"| node_app
node_app -->|"parses arguments"| node_parser
node_parser -->|"discovers and reads"| node_ottofile
node_parser -->|"builds config"| node_cfg
node_parser -->|"resolves foreach"| node_resolver
node_app -->|"builds executor tasks"| node_task
node_app -->|"executes plan"| node_scheduler
node_scheduler -->|"orders dependencies"| node_dag
node_scheduler -->|"runs actions"| node_action
node_action -->|"spawns processes"| node_shell
node_scheduler -->|"streams output"| node_output
node_app -->|"manages run"| node_workspace
node_app -->|"records completion"| node_state
node_state -->|"reads and writes"| node_database
node_app -->|"starts dashboard"| node_tui
node_scheduler -->|"publishes task updates"| node_tui
node_app -->|"dispatches builtin"| node_graphcmd
node_app -->|"lists tasks"| node_tasks
node_app -->|"dispatches builtin"| node_clean
node_app -->|"dispatches builtin"| node_convert
node_convert -->|"converts input"| node_makefile
node_app -->|"dispatches builtin"| node_historycmd
node_historycmd -->|"queries history"| node_state
node_app -->|"dispatches builtin"| node_stats
node_stats -->|"queries statistics"| node_state
node_app -->|"dispatches builtin"| node_upgrade
node_upgrade -.->|"downloads upgrade"| node_release

click node_main "https://github.com/otto-rs/otto/blob/main/src/main.rs"
click node_app "https://github.com/otto-rs/otto/blob/main/src/app.rs"
click node_tui "https://github.com/otto-rs/otto/blob/main/src/tui/app.rs"
click node_parser "https://github.com/otto-rs/otto/blob/main/src/cli/parser.rs"
click node_cfg "https://github.com/otto-rs/otto/blob/main/src/cfg/config.rs"
click node_resolver "https://github.com/otto-rs/otto/blob/main/src/cfg/resolver.rs"
click node_makefile "https://github.com/otto-rs/otto/blob/main/src/makefile/converter.rs"
click node_task "https://github.com/otto-rs/otto/blob/main/src/executor/task.rs"
click node_dag "https://github.com/otto-rs/otto/blob/main/src/executor/graph.rs"
click node_scheduler "https://github.com/otto-rs/otto/blob/main/src/executor/scheduler.rs"
click node_action "https://github.com/otto-rs/otto/blob/main/src/executor/action.rs"
click node_output "https://github.com/otto-rs/otto/blob/main/src/executor/output.rs"
click node_workspace "https://github.com/otto-rs/otto/blob/main/src/executor/workspace.rs"
click node_state "https://github.com/otto-rs/otto/blob/main/src/executor/state/manager.rs"
click node_database "https://github.com/otto-rs/otto/blob/main/src/executor/state/db.rs"
click node_graphcmd "https://github.com/otto-rs/otto/blob/main/src/cli/commands/graph.rs"
click node_tasks "https://github.com/otto-rs/otto/blob/main/src/cli/commands/tasks.rs"
click node_clean "https://github.com/otto-rs/otto/blob/main/src/cli/commands/clean.rs"
click node_convert "https://github.com/otto-rs/otto/blob/main/src/cli/commands/convert.rs"
click node_historycmd "https://github.com/otto-rs/otto/blob/main/src/cli/commands/history.rs"
click node_stats "https://github.com/otto-rs/otto/blob/main/src/cli/commands/stats.rs"
click node_upgrade "https://github.com/otto-rs/otto/blob/main/src/cli/commands/upgrade.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_main,node_app,node_tui toneBlue
class node_parser,node_cfg,node_resolver toneAmber
class node_task,node_dag,node_scheduler,node_action,node_output,node_workspace toneMint
class node_state,node_database,node_shell toneRose
class node_makefile,node_graphcmd,node_tasks,node_clean,node_convert,node_historycmd,node_stats,node_upgrade,node_user,node_release,node_ottofile toneIndigo
```

## Components

### CLI and UI

- [CLI entry](https://github.com/otto-rs/otto/blob/main/src/main.rs): `src/main.rs`
- [Application](https://github.com/otto-rs/otto/blob/main/src/app.rs): `src/app.rs`
- [TUI dashboard](https://github.com/otto-rs/otto/blob/main/src/tui/app.rs): `src/tui/app.rs`

### Task configuration

- [CLI parser](https://github.com/otto-rs/otto/blob/main/src/cli/parser.rs): `src/cli/parser.rs`
- [Config model](https://github.com/otto-rs/otto/blob/main/src/cfg/config.rs): `src/cfg/config.rs`
- [Foreach resolver](https://github.com/otto-rs/otto/blob/main/src/cfg/resolver.rs): `src/cfg/resolver.rs`

### Task execution

- [Executor tasks](https://github.com/otto-rs/otto/blob/main/src/executor/task.rs): `src/executor/task.rs`
- [Dependency graph](https://github.com/otto-rs/otto/blob/main/src/executor/graph.rs): `src/executor/graph.rs`
- [Task scheduler](https://github.com/otto-rs/otto/blob/main/src/executor/scheduler.rs): `src/executor/scheduler.rs`
- [Action processor](https://github.com/otto-rs/otto/blob/main/src/executor/action.rs): `src/executor/action.rs`
- [Task output](https://github.com/otto-rs/otto/blob/main/src/executor/output.rs): `src/executor/output.rs`
- [Run workspace](https://github.com/otto-rs/otto/blob/main/src/executor/workspace.rs): `src/executor/workspace.rs`

### Run history

- [Run state](https://github.com/otto-rs/otto/blob/main/src/executor/state/manager.rs): `src/executor/state/manager.rs`
- [SQLite database](https://github.com/otto-rs/otto/blob/main/src/executor/state/db.rs): `src/executor/state/db.rs`

### Built-in commands

- [Makefile converter](https://github.com/otto-rs/otto/blob/main/src/makefile/converter.rs): `src/makefile/converter.rs`
- [Graph command](https://github.com/otto-rs/otto/blob/main/src/cli/commands/graph.rs): `src/cli/commands/graph.rs`
- [Task listing](https://github.com/otto-rs/otto/blob/main/src/cli/commands/tasks.rs): `src/cli/commands/tasks.rs`
- [Clean command](https://github.com/otto-rs/otto/blob/main/src/cli/commands/clean.rs): `src/cli/commands/clean.rs`
- [Convert command](https://github.com/otto-rs/otto/blob/main/src/cli/commands/convert.rs): `src/cli/commands/convert.rs`
- [History command](https://github.com/otto-rs/otto/blob/main/src/cli/commands/history.rs): `src/cli/commands/history.rs`
- [Stats command](https://github.com/otto-rs/otto/blob/main/src/cli/commands/stats.rs): `src/cli/commands/stats.rs`
- [Upgrade command](https://github.com/otto-rs/otto/blob/main/src/cli/commands/upgrade.rs): `src/cli/commands/upgrade.rs`

### Other components

- **Engineer**
- **Release service**
- **Ottofile**
- **Task processes**

## Connections

- Engineer → CLI entry: invokes
- CLI entry → Application: runs
- Application → CLI parser: parses arguments
- CLI parser → Ottofile: discovers and reads
- CLI parser → Config model: builds config
- CLI parser → Foreach resolver: resolves foreach
- Application → Executor tasks: builds executor tasks
- Application → Task scheduler: executes plan
- Task scheduler → Dependency graph: orders dependencies
- Task scheduler → Action processor: runs actions
- Action processor → Task processes: spawns processes
- Task scheduler → Task output: streams output
- Application → Run workspace: manages run
- Application → Run state: records completion
- Run state → SQLite database: reads and writes
- Application → TUI dashboard: starts dashboard
- Task scheduler → TUI dashboard: publishes task updates
- Application → Graph command: dispatches builtin
- Application → Task listing: lists tasks
- Application → Clean command: dispatches builtin
- Application → Convert command: dispatches builtin
- Convert command → Makefile converter: converts input
- Application → History command: dispatches builtin
- History command → Run state: queries history
- Application → Stats command: dispatches builtin
- Stats command → Run state: queries statistics
- Application → Upgrade command: dispatches builtin
- Upgrade command → Release service: downloads upgrade