# codad5/fli architecture

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

- Interactive diagram: https://gitdiagram.com/codad5/fli
- Repository: https://github.com/codad5/fli

## Overview

##### Project Type and Purpose
- FLI is an open-source Rust library for building CLI apps (in the style of commander.js).
- It exposes a procedural macro to bootstrap apps from Cargo.toml and a runtime API (Fli struct) for commands, options, and callbacks.

##### File Structure
Top level:
- .github/workflows: CI/CD (publish to crates.io)
- Dockerfile & docker-compose.yaml: containerize tests/sample
- Cargo.toml: crate metadata + dependencies
- sample/: example binary that uses FLI
- src/: library code
– lib.rs: public API entrypoint
– fli.rs: core engine (parser, dispatcher)
– macros.rs: proc-macro for init_fli_from_toml!
– tests.rs + tests/: unit tests

##### Extract Architectural Patterns
- Macro + Core-Library Pattern
- Modular design: parsing, command registration, option handling, callback execution
- CI/CD pipeline (GitHub Actions → crates.io)
- Example app illustrating integration

##### Main Components
A. User’s Application (sample/main.rs)
B. Procedural Macro (macros.rs)
C. FLI Core Engine (fli.rs)
1. Parser Module
2. Command & Option Builder
3. Callback Registry & Executor
4. Config Loader (reads Cargo.toml via the macro)
D. Public API Surface (lib.rs)
E. Tests (src/tests.rs + tests/)
F. CI/CD Pipeline (GitHub Actions workflow)
G. Containerization (Dockerfile, docker-compose)

##### Relationships & Data Flows
1. At compile time:
- sample app uses `init_fli_from_toml!` → macros.rs expands into initialization code
2. At runtime:
- User runs `myapp [command] [options]`
→ Parser Module reads `std::env::args()`
→ Matches against registered commands/options (Command & Option Builder data)
→ Populates values, checks required vs. optional
→ Dispatcher invokes user callbacks via Callback Registry
→ Outputs via stdout/stderr
3. Testing & CI:
- Unit tests import lib.rs → fli.rs → macros.rs
- GitHub Actions runs `cargo test`, `cargo publish` on tags
- Dockerfile & compose spin up a container for sample/demo

##### Technologies & Frameworks
- Rust (Cargo, crates.io)
- Procedural Macros
- GitHub Actions (publish.yml)
- Docker / docker-compose

##### Putting It All Together
Top row (Compile & CI):
[sample/main.rs] → (macro expansion) → [macros.rs]
[Cargo.toml] ──┐
↓
[lib.rs] ──→ [fli core modules]
Middle row (Runtime):
[User CLI Input] → [Parser] → [Command/Option Registry] → [Callback Executor] → [Stdout]
Bottom row (Infrastructure):
[GitHub Actions] → [crates.io publish]
[Dockerfile/docker-compose] → [Container for sample/test]

## Diagram (Mermaid)

```mermaid
graph TB

  subgraph "Compile-Time Layer"
    SM["sample/src/main.rs"]:::integration
    SCM["sample/Cargo.toml"]:::integration
    macros["Procedural Macro\n(init_fli_from_toml!)"]:::library
    rootCargo["Cargo.toml"]:::integration
    lib["Public API\n(Fli struct, exposed functions)"]:::library
    fliCore["FLI Core Engine\n(Parser, Dispatcher, Config Loader)"]:::library
    testsEntry["Unit Tests\n(src/tests.rs)"]:::library
    testsSpec["FLI-Specific Tests\n(src/tests/fli_test.rs)"]:::library
  end

  SM -->|"uses macro"| macros
  SCM -->|"provides metadata"| macros
  macros -->|"expands into API calls"| lib
  rootCargo -->|"crate metadata"| lib
  lib -->|"calls core engine"| fliCore
  testsEntry -->|"imports library"| lib
  testsEntry -->|"tests core"| fliCore
  testsEntry -->|"tests macros"| macros
  testsEntry --> testsSpec

  subgraph "Runtime Layer"
    cli["User CLI Input\n(myapp [command] [options])"]:::runtime
    parser["Parser Module\n(reads std::env::args())"]:::runtime
    registry["Command & Option Registry"]:::runtime
    executor["Callback Executor\n(Callback Registry)"]:::runtime
    stdout["Stdout/Stderr Output"]:::runtime
  end

  cli --> parser
  parser --> registry
  registry --> executor
  executor --> stdout

  subgraph "Infrastructure"
    ci["GitHub Actions\n(.github/workflows/publish.yml)"]:::infra
    crateIO["crates.io (Registry)"]:::infra
    dockerfile["Dockerfile"]:::infra
    compose["docker-compose.yaml"]:::infra
    sampleContainer["Sample/Test Container"]:::infra
  end

  ci -->|"publishes on tags"| crateIO
  dockerfile --> sampleContainer
  compose --> sampleContainer

  click SM "https://github.com/codad5/fli/blob/master/sample/src/main.rs"
  click SCM "https://github.com/codad5/fli/blob/master/sample/Cargo.toml"
  click macros "https://github.com/codad5/fli/blob/master/src/macros.rs"
  click rootCargo "https://github.com/codad5/fli/blob/master/Cargo.toml"
  click lib "https://github.com/codad5/fli/blob/master/src/lib.rs"
  click fliCore "https://github.com/codad5/fli/blob/master/src/fli.rs"
  click testsEntry "https://github.com/codad5/fli/blob/master/src/tests.rs"
  click testsSpec "https://github.com/codad5/fli/blob/master/src/tests/fli_test.rs"
  click ci "https://github.com/codad5/fli/blob/master/.github/workflows/publish.yml"
  click dockerfile "https://github.com/codad5/fli/tree/master/Dockerfile"
  click compose "https://github.com/codad5/fli/blob/master/docker-compose.yaml"

  classDef library fill:#ADD8E6,stroke:#000000
  classDef runtime fill:#90EE90,stroke:#000000
  classDef integration fill:#FFA500,stroke:#000000
  classDef infra fill:#D3D3D3,stroke:#000000
```
