# intersectmbo/cardano-cli architecture

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

- Interactive diagram: https://gitdiagram.com/intersectmbo/cardano-cli
- Repository: https://github.com/intersectmbo/cardano-cli

## Overview

##### Main Components
- CLI Application Core: At the heart is the “cardano-cli” executable (with entry point cardano-cli.hs). This layer is responsible for reading user input, parsing command-line options, and dispatching commands.
- Command Modules & Subsystems: Under the “src/Cardano/CLI” directory, there are many modules segmented by eras (Byron, EraBased, EraIndependent, and Compatible subdirectories). Each submodule handles specific commands such as genesis creation, key management, transaction building, governance actions, and delegation.
- Common Libraries & Utilities: Modules providing common types, error handling (in the “Type/Error” directories), JSON handling, IO utilities, and command-line parsing.
- Testing & Golden Files: A separate “test” hierarchy contains golden tests and a suite of test utilities that confirm the correctness of CLI commands. This is crucial for ensuring stability across protocol eras.
- Scripts and CI/CD Infrastructure: Directories such as “scripts/”, “.github/”, and “flake.nix” indicate an ecosystem for building, testing (e.g., via GitHub actions, CI scripts) and releasing the CLI application.

##### Component Relationships & Interactions
- Each command module interacts with core libraries for functionality such as key conversions, JSON rendering, IO operations, and error reporting. Show internal communication lines between “Command Modules” and “Utility & Library Modules.”
- Testing components “Golden Tests” and “CLI Test Libraries” feed input into the command modules to verify expected outputs. Illustrate a separate testing subsystem which “overrides” or “simulates” the command behavior.
- Scripts and CI/CD pipelines are external orchestrators that build, test, and deploy releases. They interface with the build system (Cabal, flake.nix) and trigger test suites.
- External blockchain or cardano‑node: Indicate that some commands (e.g., those sending transactions or querying the ledger) communicate with an external “Cardano Node” component.

##### Important Architectural Patterns
- Multi-Era Support and Abstraction: Distinct directories indicate different strategies for handling differences between blockchain eras. Use grouping to show “EraBased”, “EraIndependent”, and “Compatible” modules as layers on top of the common CLI core.
- Test-Driven Validation: The extensive golden tests and test libraries highlight the emphasis on regression testing and validation of command outputs. Represent this as an orthogonal testing layer.

##### Relevant Technologies & Tools
- Programming Language: Haskell (based on .cabal files and Haskell source code in the “src/” directories).
- Build System & Package Management: Cabal, flake.nix for Nix-based development.
- CI Systems: GitHub Actions, GitLab CI (as evidenced by workflow YAML files), and various shell scripts.
- Testing Frameworks: Golden tests, integration tests, and custom Haskell test libraries.
- External Interfacing: Cardano node and external command-line usage documentation.

##### Final Advice
- Decomposing the project into as many detailed components as possible, while maintaining a clear overall flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User Input"]:::input
    B["CLI Parser/Dispatcher (cardano-cli)"]:::cliCore
    A -->|"reads"| B
    %% CLI Core invokes command modules
    B -->|"dispatches"| C
    subgraph "Command Modules & Subsystems"
        C["Era-Specific Command Modules (Byron,EraBased,Compatible,...)"]:::module
    end

    %% Command modules use common libraries and utilities
    subgraph "Common Libraries & Utilities"
        D1["Helper Module"]:::utility
        D2["IO Utilities"]:::utility
        D3["Error Handling"]:::utility
        D4["JSON Utilities"]:::utility
    end
    C -->|"uses"| D1
    C -->|"uses"| D2
    C -->|"uses"| D3
    C -->|"uses"| D4

    %% Command modules call external Cardano Node Interface
    E((Cardano Node Interface)):::external
    C -->|"calls"| E

    %% External configuration provides settings
    H["External Configuration (Cardano Config)"]:::externalConfig
    H -->|"configures"| E
    H -->|"configures"| C

    %% Testing Suite validates command modules
    subgraph "Testing Suite"
        F1["Golden Test Suite"]:::testing
        F2["CLI Test Libraries"]:::testing
    end
    F1 -->|"verifies"| C
    F2 -->|"verifies"| C

    %% Scripts & CI/CD infrastructure
    subgraph "Scripts & CI/CD"
        G1["Workflows"]:::scripts
        G2["GitHub Binaries"]:::scripts
        G3["flake.nix"]:::scripts
        G4["cabal.project"]:::scripts
        G5["CI Shell Scripts"]:::scripts
    end
    G1 -->|"builds"| B
    G5 -->|"triggers"| F1

    %% Styles
    classDef input fill:#fdfd96,stroke:#000,stroke-width:2px;
    classDef cliCore fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef module fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef utility fill:#ffdead,stroke:#000,stroke-width:2px;
    classDef testing fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef scripts fill:#d3d3d3,stroke:#000,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#000,stroke-width:2px;
    classDef externalConfig fill:#ffb6c1,stroke:#000,stroke-width:2px;

    %% Click Events
    click B "https://github.com/intersectmbo/cardano-cli/blob/master/cardano-cli/app/cardano-cli.hs"
    click C "https://github.com/intersectmbo/cardano-cli/tree/master/cardano-cli/src/Cardano/CLI"
    click D1 "https://github.com/intersectmbo/cardano-cli/blob/master/cardano-cli/src/Cardano/CLI/Helper.hs"
    click D2 "https://github.com/intersectmbo/cardano-cli/tree/master/cardano-cli/src/Cardano/CLI/IO"
    click D3 "https://github.com/intersectmbo/cardano-cli/tree/master/cardano-cli/src/Cardano/CLI/Type/Error"
    click D4 "https://github.com/intersectmbo/cardano-cli/tree/master/cardano-cli/src/Cardano/CLI/Json"
    click F1 "https://github.com/intersectmbo/cardano-cli/tree/master/cardano-cli/test/cardano-cli-golden"
    click F2 "https://github.com/intersectmbo/cardano-cli/tree/master/cardano-cli/test/cardano-cli-test"
    click G1 "https://github.com/intersectmbo/cardano-cli/tree/master/.github/workflows"
    click G2 "https://github.com/intersectmbo/cardano-cli/tree/master/.github/bin"
    click G3 "https://github.com/intersectmbo/cardano-cli/blob/master/flake.nix"
    click G4 "https://github.com/intersectmbo/cardano-cli/blob/master/cabal.project"
    click G5 "https://github.com/intersectmbo/cardano-cli/tree/master/scripts/ci"
    click H "https://github.com/intersectmbo/cardano-cli/tree/master/configuration/cardano"
```
