# anchore/binny architecture

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

- Interactive diagram: https://gitdiagram.com/anchore/binny
- Repository: https://github.com/anchore/binny

## Overview

##### Main Components
- **CLI Frontend (cmd/binny)**
- Entry point (`main.go`) invoking Cobra commands under `cmd/binny/cli/command`
- Parses flags, subcommands: install, check, update, list, add
- **Core Engine**
- **Configuration Loader** (`.binny.yaml`) → internal data structures
- **Event Bus** (`internal/bus`) for decoupled event handling
- **Task Executor** (`event/`) that drives operations per tool
- **Install & Version Modules** (`tool/` & `cmd/binny/cli/internal/yamlpatch`)
- Multiple install methods: `githubrelease`, `goinstall`, `hostedshell`
- Multiple version resolvers: `github-release`, `go-proxy`, `git`, etc.
- **State Store**
- Local JSON store (`store.go` at project root) representing installed binaries
- Directory layout under user‐specified install path (e.g. `$DEST/bin/`)
- **External Services**
- GitHub Releases API
- Go Proxy (`proxy.golang.org`)
- Git repos on disk (for `git` resolver)
- Hosted shell scripts (arbitrary URLs)
- **Supporting Utilities**
- Logging & redaction (`internal/log`, `internal/redact`)
- File download & checksum (`internal/download_file`)
- Semver parsing (`internal/semver`)

##### Relationships & Data Flow
- The frontend reads the **Config File**, then dispatches a command event into the **Event Bus**.
- The **Task Executor** picks up events, coordinates the **Install & Version Modules**.
- Each module may:
- Call out to an **External Service**
- Download binaries or run `go install`
- Emit events (success/failure) back on the bus
- On success, the **State Store** is updated (writes JSON).
- The CLI returns status and prints output via UI components (`internal/ui`).

##### Architectural Patterns
- **Modular Plugins**: Each install method and resolver is a swap-in module under `tool/`.
- **Event-Driven Core**: The central bus decouples CLI commands from execution logic.
- **Separation of Concerns**:
- CLI concerns in `cmd/`
- Business logic in `internal/` & `tool/`
- Persistence in `store.go`
- Testing scaffolds in `test/`, `tool/*/testdata`

##### Diagramming Advice
- CLI Frontend, Config Loader, Event Bus, Executor, Modules, Store, External Services
- Green = User-facing (CLI/UI)
- Blue = Core Engine
- Orange = External integrations
- Gray = Persistence

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Frontend Layer
    user["User"]:::frontend
    user -->|runs command| cli["Golang CLI (Cobra)\n(cmd/binny)"]:::frontend

    %% CLI Frontend internals
    subgraph "CLI Frontend" 
        cli_cmds["CLI Commands\n(cmd/binny/cli/command/*.go)"]:::frontend
        cli_core["CLI Core\n(cmd/binny/cli/cli.go)"]:::frontend
    end
    cli --> cli_core
    cli_core --> cli_cmds

    %% Configuration Loader
    config["Configuration Loader\n(.binny.yaml & tool/config.go)"]:::core

    %% Event Bus
    bus["Event Bus\n(internal/bus)"]:::core

    %% Task Executor
    executor["Task Executor\n(event/)"]:::core

    %% Install & Version Modules
    subgraph "Install & Version Modules" 
        ghrel["GitHub Release Module"]:::core
        goinst["Go Install Module"]:::core
        hostsh["Hosted Shell Module"]:::core
        goproxy["Go Proxy Resolver"]:::core
        gitres["Git Resolver"]:::core
    end

    %% External Services
    subgraph "External Services" 
        github_api["GitHub Releases API"]:::external
        go_proxy["Go Proxy (proxy.golang.org)"]:::external
        git_repo["Git Repos"]:::external
        shell_host["Hosted Shell Scripts"]:::external
    end

    %% Persistence
    store["State Store\n(store.go)"]:::persistence

    %% UI Components
    ui["CLI UI Components\n(internal/ui & cli/ui)"]:::frontend

    %% Data & Control Flows
    cli_core -->|parse config| config
    cli_core -->|dispatch command event| bus
    config -->|load settings| executor
    bus -->|emit task event| executor
    executor -->|invoke module| ghrel
    executor -->|invoke module| goinst
    executor -->|invoke module| hostsh
    executor -->|invoke module| goproxy
    executor -->|invoke module| gitres

    ghrel -->|call API| github_api
    goinst -->|run go install| go_proxy
    hostsh -->|download script| shell_host
    goproxy -->|query proxy| go_proxy
    gitres -->|clone/fetch| git_repo

    ghrel -.->|emit result| bus
    goinst -.->|emit result| bus
    hostsh -.->|emit result| bus
    goproxy -.->|emit result| bus
    gitres -.->|emit result| bus

    bus -->|on success| store
    bus -->|on success| ui
    ui -->|output status| user

    %% Click Events
    click cli "https://github.com/anchore/binny/blob/main/cmd/binny/main.go"
    click cli_core "https://github.com/anchore/binny/blob/main/cmd/binny/cli/cli.go"
    click cli_cmds "https://github.com/anchore/binny/tree/main/cmd/binny/cli/command"
    click config "https://github.com/anchore/binny/blob/main/tool/config.go"
    click bus "https://github.com/anchore/binny/blob/main/internal/bus/bus.go"
    click executor "https://github.com/anchore/binny/blob/main/event/task.go"
    click ghrel "https://github.com/anchore/binny/blob/main/tool/githubrelease/installer.go"
    click goinst "https://github.com/anchore/binny/blob/main/tool/goinstall/installer.go"
    click hostsh "https://github.com/anchore/binny/blob/main/tool/hostedshell/installer.go"
    click goproxy "https://github.com/anchore/binny/blob/main/tool/goproxy/methods.go"
    click gitres "https://github.com/anchore/binny/blob/main/tool/git/methods.go"
    click store "https://github.com/anchore/binny/blob/main/store.go"
    click ui "https://github.com/anchore/binny/tree/main/cmd/binny/cli/internal/ui"

    %% Styles
    classDef frontend fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef external fill:#f96,stroke:#333,stroke-width:1px
    classDef persistence fill:#ccc,stroke:#333,stroke-width:1px
```
