# falconiere/toolu architecture

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

- Interactive diagram: https://gitdiagram.com/falconiere/toolu
- Repository: https://github.com/falconiere/toolu

## Overview

toolu is a Rust-based set of AI-agent plugins and a native CLI that applies engineering checks and delivery workflows across several coding-agent hosts. The main path is an agent edit triggering a hook, which routes through the CLI and engine to configured quality checks; quality gates can then block commits or pushes. Separate branches provide structured code review and epic orchestration. The README supports the product-level workflow and plugin relationships; sampled source confirms selected review and orchestration internals, but not every runtime dispatch.

Main entry points: [`crates/core/engine/src/lib.rs`](https://github.com/falconiere/toolu/blob/main/crates/core/engine/src/lib.rs) (Gate Engine), [`crates/code-review/src/pipeline.rs`](https://github.com/falconiere/toolu/blob/main/crates/code-review/src/pipeline.rs) (Review Pipeline), [`crates/code-review/src/cli.rs`](https://github.com/falconiere/toolu/blob/main/crates/code-review/src/cli.rs) (Review Command), [`crates/epic-orchestrator/src/server.rs`](https://github.com/falconiere/toolu/blob/main/crates/epic-orchestrator/src/server.rs) (Epic Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Hooks"]
  node_cli["Native CLI<br/>[main.rs]"]
  node_hook["Hook Runtime<br/>[hook.rs]"]
  node_registry["Plugin Registry<br/>[registry.rs]"]
end

subgraph group_engine["Quality Engine"]
  node_engine["Gate Engine<br/>[lib.rs]"]
  node_quality["Language Checks<br/>[lib.rs]"]
  node_tsquality["TypeScript Checks<br/>[lib.rs]"]
  node_pyquality["Python Checks<br/>[lib.rs]"]
  node_shell["Shell Analysis<br/>[analysis.rs]"]
end

subgraph group_review["Code Review"]
  node_reviewcli["Review Command<br/>[cli.rs]"]
  node_pipeline["Review Pipeline<br/>[pipeline.rs]"]
  node_shaper["Diff Shaping<br/>[shape.rs]"]
  node_reviewer["Model Review<br/>[review.rs]"]
  node_reviewcontract["Review Report<br/>[contract.rs]"]
  node_reviewmemory[("Review Memory<br/>[memory.rs]")]
end

subgraph group_delivery["Delivery and Orchestration"]
  node_flow["Delivery Workflow<br/>[lib.rs]"]
  node_orchestrator["Epic Orchestrator<br/>[server.rs]"]
  node_githubchecks["GitHub Checks<br/>[github_engine.rs]"]
  node_journal[("Event Journal<br/>[journal.rs]")]
end

node_agent(("Coding Agent"))

node_agent -->|"triggers on edits"| node_hook
node_hook -->|"runs native CLI"| node_cli
node_cli -.->|"routes hook checks"| node_engine
node_registry -->|"registers modules"| node_engine
node_engine -.->|"runs language rules"| node_quality
node_engine -.->|"runs language rules"| node_tsquality
node_engine -.->|"runs language rules"| node_pyquality
node_engine -.->|"checks shell changes"| node_shell
node_agent -.->|"requests review"| node_reviewcli
node_reviewcli -.->|"starts review"| node_pipeline
node_pipeline -->|"shapes diff"| node_shaper
node_pipeline -->|"reviews chunks"| node_reviewer
node_reviewer -.->|"produces findings"| node_reviewcontract
node_pipeline -->|"loads prior memory"| node_reviewmemory
node_reviewcli -.->|"supports workflow"| node_flow
node_agent -->|"follows checkpoints"| node_flow
node_flow -->|"used by epics"| node_orchestrator
node_orchestrator -.->|"runs check feeds"| node_githubchecks
node_githubchecks -.->|"records events"| node_journal
node_orchestrator -->|"appends usage"| node_journal

click node_cli "https://github.com/falconiere/toolu/blob/main/crates/cli/src/main.rs"
click node_hook "https://github.com/falconiere/toolu/blob/main/crates/cli/src/hook.rs"
click node_registry "https://github.com/falconiere/toolu/blob/main/crates/cli/src/registry.rs"
click node_engine "https://github.com/falconiere/toolu/blob/main/crates/core/engine/src/lib.rs"
click node_quality "https://github.com/falconiere/toolu/blob/main/crates/rust-quality/src/lib.rs"
click node_tsquality "https://github.com/falconiere/toolu/blob/main/crates/ts-quality/src/lib.rs"
click node_pyquality "https://github.com/falconiere/toolu/blob/main/crates/python-quality/src/lib.rs"
click node_shell "https://github.com/falconiere/toolu/blob/main/crates/core/shell/src/analysis.rs"
click node_reviewcli "https://github.com/falconiere/toolu/blob/main/crates/code-review/src/cli.rs"
click node_pipeline "https://github.com/falconiere/toolu/blob/main/crates/code-review/src/pipeline.rs"
click node_shaper "https://github.com/falconiere/toolu/blob/main/crates/code-review/src/shape.rs"
click node_reviewer "https://github.com/falconiere/toolu/blob/main/crates/code-review/src/review.rs"
click node_reviewcontract "https://github.com/falconiere/toolu/blob/main/crates/code-review/src/contract.rs"
click node_reviewmemory "https://github.com/falconiere/toolu/blob/main/crates/code-review/src/memory.rs"
click node_flow "https://github.com/falconiere/toolu/blob/main/crates/delivery-flow/src/lib.rs"
click node_orchestrator "https://github.com/falconiere/toolu/blob/main/crates/epic-orchestrator/src/server.rs"
click node_githubchecks "https://github.com/falconiere/toolu/blob/main/crates/epic-orchestrator/src/github_engine.rs"
click node_journal "https://github.com/falconiere/toolu/blob/main/crates/epic-orchestrator/src/journal.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_cli,node_hook,node_registry toneBlue
class node_engine,node_quality,node_tsquality,node_pyquality,node_shell toneAmber
class node_reviewcli,node_pipeline,node_shaper,node_reviewer,node_reviewcontract,node_reviewmemory toneMint
class node_flow,node_orchestrator,node_githubchecks,node_journal toneRose
class node_agent toneIndigo
```

## Components

### CLI and Hooks

- [Native CLI](https://github.com/falconiere/toolu/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- [Hook Runtime](https://github.com/falconiere/toolu/blob/main/crates/cli/src/hook.rs): `crates/cli/src/hook.rs`
- [Plugin Registry](https://github.com/falconiere/toolu/blob/main/crates/cli/src/registry.rs): `crates/cli/src/registry.rs`

### Quality Engine

- [Gate Engine](https://github.com/falconiere/toolu/blob/main/crates/core/engine/src/lib.rs): `crates/core/engine/src/lib.rs`
- [Language Checks](https://github.com/falconiere/toolu/blob/main/crates/rust-quality/src/lib.rs): `crates/rust-quality/src/lib.rs`
- [TypeScript Checks](https://github.com/falconiere/toolu/blob/main/crates/ts-quality/src/lib.rs): `crates/ts-quality/src/lib.rs`
- [Python Checks](https://github.com/falconiere/toolu/blob/main/crates/python-quality/src/lib.rs): `crates/python-quality/src/lib.rs`
- [Shell Analysis](https://github.com/falconiere/toolu/blob/main/crates/core/shell/src/analysis.rs): `crates/core/shell/src/analysis.rs`

### Code Review

- [Review Command](https://github.com/falconiere/toolu/blob/main/crates/code-review/src/cli.rs): `crates/code-review/src/cli.rs`
- [Review Pipeline](https://github.com/falconiere/toolu/blob/main/crates/code-review/src/pipeline.rs): `crates/code-review/src/pipeline.rs`
- [Diff Shaping](https://github.com/falconiere/toolu/blob/main/crates/code-review/src/shape.rs): `crates/code-review/src/shape.rs`
- [Model Review](https://github.com/falconiere/toolu/blob/main/crates/code-review/src/review.rs): `crates/code-review/src/review.rs`
- [Review Report](https://github.com/falconiere/toolu/blob/main/crates/code-review/src/contract.rs): `crates/code-review/src/contract.rs`
- [Review Memory](https://github.com/falconiere/toolu/blob/main/crates/code-review/src/memory.rs): `crates/code-review/src/memory.rs`

### Delivery and Orchestration

- [Delivery Workflow](https://github.com/falconiere/toolu/blob/main/crates/delivery-flow/src/lib.rs): `crates/delivery-flow/src/lib.rs`
- [Epic Orchestrator](https://github.com/falconiere/toolu/blob/main/crates/epic-orchestrator/src/server.rs): `crates/epic-orchestrator/src/server.rs`
- [GitHub Checks](https://github.com/falconiere/toolu/blob/main/crates/epic-orchestrator/src/github_engine.rs): `crates/epic-orchestrator/src/github_engine.rs`
- [Event Journal](https://github.com/falconiere/toolu/blob/main/crates/epic-orchestrator/src/journal.rs): `crates/epic-orchestrator/src/journal.rs`

### Other components

- **Coding Agent**

## Connections

- Coding Agent → Hook Runtime: triggers on edits (evidence: `README.md`)
- Hook Runtime → Native CLI: runs native CLI (evidence: `README.md`)
- Native CLI → Gate Engine: routes hook checks
- Plugin Registry → Gate Engine: registers modules (evidence: `README.md`)
- Gate Engine → Language Checks: runs language rules
- Gate Engine → TypeScript Checks: runs language rules
- Gate Engine → Python Checks: runs language rules
- Gate Engine → Shell Analysis: checks shell changes
- Coding Agent → Review Command: requests review
- Review Command → Review Pipeline: starts review (evidence: `crates/code-review/src/pipeline.rs`)
- Review Pipeline → Diff Shaping: shapes diff (evidence: `crates/code-review/src/pipeline.rs`)
- Review Pipeline → Model Review: reviews chunks (evidence: `crates/code-review/src/pipeline.rs`)
- Model Review → Review Report: produces findings (evidence: `crates/code-review/src/review.rs`)
- Review Pipeline → Review Memory: loads prior memory (evidence: `crates/code-review/src/pipeline.rs`)
- Review Command → Delivery Workflow: supports workflow
- Coding Agent → Delivery Workflow: follows checkpoints (evidence: `README.md`)
- Delivery Workflow → Epic Orchestrator: used by epics (evidence: `README.md`)
- Epic Orchestrator → GitHub Checks: runs check feeds (evidence: `crates/epic-orchestrator/src/github_engine.rs`)
- GitHub Checks → Event Journal: records events (evidence: `crates/epic-orchestrator/src/github_engine.rs`)
- Epic Orchestrator → Event Journal: appends usage (evidence: `crates/epic-orchestrator/src/engine_usage.rs`)