# pulp-platform/bender architecture

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

- Interactive diagram: https://gitdiagram.com/pulp-platform/bender
- Repository: https://github.com/pulp-platform/bender

## Overview

##### Project Type and Purpose
- This is a Rust-based command-line application (no GUI or web frontend) called **bender** that manages hardware-design dependencies and generates build/simulation scripts.
- Its core responsibilities are: parsing manifests (`Bender.yml`), resolving versions (semantic or git), checking out dependencies, collecting source files, generating tool-specific scripts via Tera templates, and managing vendored code.

##### File Structure
- Top-level Rust project files: `Cargo.toml`, `src/`, `tests/`, `.github/`, various licenses.
- `src/main.rs` and `src/cli.rs`: entry point and argument parsing.
- `src/cmd/…`: subcommands (checkout, update, sources, script, vendor, etc.).
- Core modules: `config.rs` (configuration loading/merging), `resolver.rs` (dependency resolution), `git.rs` (git wrapper), `lockfile.rs` (lock-file read/write), `src.rs` (source collection), `sess.rs` (interactive session), `target.rs` (target expression logic), `util.rs`, `error.rs`.
- Template files under `src/script_fmt/*.tera` power the script generation commands.
- Tests in `tests/` invoke the CLI in shell scripts to validate behavior.

a. CLI Frontend
- Parses command and flags (Clap or StructOpt in `cli.rs`).
- Dispatches to a Command Handler (one per subcommand in `src/cmd/`).
b. Configuration Service
- Reads/merges `Bender.yml`, `Bender.local`, user config files.
- Exposes a unified config object.
c. Resolver Service
- Reads manifest dependencies.
- Computes version constraints and resolves to exact `git` revisions or paths.
d. Git Service
- Invokes `git` (or wrapper) to clone, checkout, update repositories.
e. Lockfile Manager
- Reads existing `Bender.lock`, writes updated lock entries.
f. Source Collector
- Processes `sources` tree: groups, includes, defines, glob patterns.
- Applies target filters (`all(...)`, `any(...)`, etc.).
g. Template Renderer
- Loads `*.tera` templates.
- Renders tool-specific scripts or file lists.
h. Vendor Manager
- Handles `vendor_package` entries: clones upstream, applies patches, diff/patch commands.
i. Session / Interactive Layer
- Manages prompts (e.g. plugin prompts, patch messages) in `sess.rs`.
j. Tests Harness
- Shell scripts that call the binary and verify exit codes or outputs.

##### Relationships and Data Flow
- User invokes `bender <command>` → CLI Frontend → appropriate Command Handler.
- Command Handler requests configuration from Configuration Service.
- For dependency-related commands (`update`, `checkout`, `clone`, `packages`, `parents`):
- Resolver Service uses Config + existing Lockfile → computes desired state.
- Lockfile Manager updates `Bender.lock`.
- Git Service synchronizes working copies.
- For source commands (`sources`, `script`, `fusesoc`):
- After checkout, Source Collector assembles file graph.
- Template Renderer emits scripts or JSON to stdout.
- Vendor Manager is invoked for `vendor` subcommands, coordinated by its Command Handler.
- Errors propagate via `error.rs`; session prompts via `sess.rs`; utilities in `util.rs`.

##### Architectural Patterns / Design Principles
- **Separation of Concerns**: each service/module focuses on one responsibility (config, resolve, git, source, rendering).
- **Modular CLI Commands**: each subcommand implemented in its own file under `src/cmd/`.
- **Plugin-style Templates**: Tera templates decoupled from core logic.
- **Immutable Lockfile**: ensures reproducible builds.
- **Expression Tree** for target filtering.

##### Technologies and Frameworks
- Programming language: Rust (Cargo build, crates like `tera`, possibly `clap`).
- Templating: Tera (`src/script_fmt/*.tera`).
- Git integration: shelling out to `git` via `git.rs`.
- Shell scripting for tests (`tests/*.sh`).
- Continuous integration: GitHub Actions (`.github/workflows/ci.yml`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User invocation
    User(["User"]):::external
    User -->|"bender <command>"| CLI[/CLI Frontend/]:::io

    %% Command Routing
    CLI -->|"dispatch"| CmdHandler[/Command Handler/]:::core

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        BenderYml[(Bender.yml)]:::persistence
        BenderLock[(Bender.lock)]:::persistence
        Templates[(Tera Templates)]:::persistence
        PatchDir[(Patch Directory)]:::persistence
    end

    %% Core Services
    subgraph "Core Services"
        direction TB
        Config["Configuration Service"]:::core
        Resolver["Resolver Service"]:::core
        Lockfile["Lockfile Manager"]:::core
        SrcColl["Source Collector"]:::core
        Template["Template Renderer"]:::core
        Vendor["Vendor Manager"]:::core
        Session["Session Layer"]:::core
        Error["Error Handling Module"]:::core
        Util["Utility Functions"]:::core
        Target["Target Expression Logic"]:::core
    end

    %% External Services
    subgraph "External/Side Effects"
        direction TB
        GitSvc["Git Service"]:::external
    end

    %% Tests Harness
    Tests["Tests Harness"]:::external

    %% Flows
    CmdHandler -->|"load config"| Config
    Config -->|"reads"| BenderYml
    CmdHandler -->|"resolve deps"| Resolver
    Resolver -->|"reads/writes"| Lockfile
    Lockfile -->|"reads/writes"| BenderLock
    Resolver -->|"git ops"| GitSvc
    CmdHandler -->|"checkout/update"| GitSvc
    CmdHandler -->|"collect sources"| SrcColl
    SrcColl -->|"file list"| Template
    Template -->|"loads templates"| Templates
    CmdHandler -->|"vendor flow"| Vendor
    Vendor -->|"git ops"| GitSvc
    Vendor -->|"apply patches"| PatchDir
    CmdHandler -->|"prompt/error handling"| Session
    CmdHandler -->|"error propagation"| Error
    CmdHandler -->|"utilities"| Util
    SrcColl -->|"target filtering"| Target
    Target -->|"filter rules"| SrcColl

    %% Tests invocation
    Tests -.->|"executes CLI"| CLI

    %% Click Events
    click CLI "https://github.com/pulp-platform/bender/blob/master/src/main.rs"
    click CmdHandler "https://github.com/pulp-platform/bender/tree/master/src/cmd/"
    click Config "https://github.com/pulp-platform/bender/blob/master/src/config.rs"
    click Resolver "https://github.com/pulp-platform/bender/blob/master/src/resolver.rs"
    click GitSvc "https://github.com/pulp-platform/bender/blob/master/src/git.rs"
    click Lockfile "https://github.com/pulp-platform/bender/blob/master/src/lockfile.rs"
    click SrcColl "https://github.com/pulp-platform/bender/blob/master/src/src.rs"
    click Template "https://github.com/pulp-platform/bender/tree/master/src/script_fmt/"
    click Vendor "https://github.com/pulp-platform/bender/blob/master/src/cmd/vendor.rs"
    click Session "https://github.com/pulp-platform/bender/blob/master/src/sess.rs"
    click Error "https://github.com/pulp-platform/bender/blob/master/src/error.rs"
    click Util "https://github.com/pulp-platform/bender/blob/master/src/util.rs"
    click Target "https://github.com/pulp-platform/bender/blob/master/src/target.rs"
    click Tests "https://github.com/pulp-platform/bender/tree/master/tests/"

    %% Styles
    classDef io fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef core fill:#D5F5E3,stroke:#000,stroke-width:1px
    classDef external fill:#F9E79F,stroke:#000,stroke-width:1px
    classDef persistence fill:#E8DAEF,stroke:#000,stroke-width:1px
```
