# tmtmtoo/cx architecture

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

- Interactive diagram: https://gitdiagram.com/tmtmtoo/cx
- Repository: https://github.com/tmtmtoo/cx

## Overview

##### Project type and purpose
- This is a Rust-based CLI utility (“cx”) that implements two subcommands for managing external command executions: “retry” (retry until success) and “supervise” (re-execute on failure up to a limit). It is a single binary, not a server or distributed system.

##### File structure
- Top-level: Cargo.toml, src/, tests/, GitHub CI configs, Makefile.
- src/main.rs: entry point, parses CLI flags/subcommands.
- src/app.rs + src/app/: contains the core application logic (component orchestrators, retry.rs, supervise.rs).
- src/app/components/: building blocks for execution (cmd_executor.rs, cmd_not_found.rs, wait.rs).
- src/config.rs: CLI → internal config model.
- src/io/: trait for executing commands, with tokio_impl.rs implementation.
- tests/: unit tests for retry and supervise modules.

##### README for additional insights
- Confirms two subcommands, each with “count” and “interval” options, invoking arbitrary shell commands.
- No external services or databases—pure local process execution.

- Break the binary into “CLI”, “Config”, “Controllers”, “Components”, “I/O Abstraction”, “OS Shell”.
- Trait boundary between executor logic and its tokio_impl.
- Callouts for test modules to demonstrate how the I/O trait enables unit testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external
    CLIParser["CLI Parser"]:::orchestration
    Config["Configuration Layer"]:::orchestration
    Dispatcher["Dispatcher"]:::orchestration

    subgraph "Controllers"
        RC["Retry Controller"]:::orchestration
        SC["Supervise Controller"]:::orchestration
    end

    subgraph "Components Layer"
        CM["Components Module"]:::orchestration
        CE["Command Executor"]:::orchestration
        CNF["Command Not Found Handler"]:::orchestration
        WT["Wait/Delay Component"]:::orchestration
    end

    subgraph "I/O Layer"
        IOTrait["I/O Abstraction Trait"]:::io
        Tokio["Tokio I/O Implementation"]:::io
    end

    OSShell["OS Shell"]:::external
    RetryTests["Retry Tests"]:::external
    SuperviseTests["Supervise Tests"]:::external

    User -->|"enter command"| CLIParser
    CLIParser -->|"parse args"| Config
    Config -->|"build config"| Dispatcher
    Dispatcher -->|"retry cmd"| RC
    Dispatcher -->|"supervise cmd"| SC

    RC -->|"execute command"| CE
    SC -->|"execute command"| CE

    CE -->|"invoke trait"| IOTrait
    IOTrait -->|"spawn process"| Tokio
    Tokio -->|"spawn child"| OSShell
    OSShell -->|"exit code"| Tokio
    Tokio -->|"return result"| IOTrait
    IOTrait -->|"result"| CE

    CE -->|"error:not found"| CNF
    CNF -->|"handle error"| CE

    RC -->|"on failure"| WT
    SC -->|"on failure"| WT
    WT -->|"sleep interval"| RC
    WT -->|"sleep interval"| SC

    RetryTests -->|"use trait mock"| IOTrait
    SuperviseTests -->|"use trait mock"| IOTrait

    click CLIParser "https://github.com/tmtmtoo/cx/blob/master/src/main.rs"
    click Config "https://github.com/tmtmtoo/cx/blob/master/src/config.rs"
    click Dispatcher "https://github.com/tmtmtoo/cx/blob/master/src/app.rs"
    click RC "https://github.com/tmtmtoo/cx/blob/master/src/app/retry.rs"
    click SC "https://github.com/tmtmtoo/cx/blob/master/src/app/supervise.rs"
    click CM "https://github.com/tmtmtoo/cx/blob/master/src/app/components.rs"
    click CE "https://github.com/tmtmtoo/cx/blob/master/src/app/components/cmd_executor.rs"
    click CNF "https://github.com/tmtmtoo/cx/blob/master/src/app/components/cmd_not_found.rs"
    click WT "https://github.com/tmtmtoo/cx/blob/master/src/app/components/wait.rs"
    click IOTrait "https://github.com/tmtmtoo/cx/blob/master/src/io.rs"
    click Tokio "https://github.com/tmtmtoo/cx/blob/master/src/io/tokio_impl.rs"
    click RetryTests "https://github.com/tmtmtoo/cx/blob/master/tests/retry.rs"
    click SuperviseTests "https://github.com/tmtmtoo/cx/blob/master/tests/supervise.rs"

    classDef orchestration fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef io fill:#D5F5E3,stroke:#145A32,color:#0B5345
    classDef external fill:#E5E7E9,stroke:#616A6B,color:#1C2833
```
