Architecture

binmate follows a layered architecture that separates the command-line interface, core business logic, persistence, provider integrations, and the terminal UI.

Project structure

cmd/                    # Command entry point
internal/
  cli/                  # CLI command definitions
    add/                # Add binary command
    config/             # Config command
    import/             # Import command
    install/            # Install command
    list/               # List command
    remove/             # Remove command
    switch/             # Switch version command
    sync/               # Sync config command
    update/             # Update command
  core/                 # Core business logic
    binary/             # Binary management service
    config/             # Configuration management
    crypto/             # Checksum verification
    install/            # Installation and extraction
    url/                # GitHub URL parsing
    version/            # Version management service
  database/             # SQLite data layer
    repository/         # Data access repositories
  providers/            # External provider integrations
    github/             # GitHub releases API
  tui/                  # Terminal UI (Bubble Tea)

Layers

• CLI (internal/cli) - Defines each command and parses user input. The root command launches the TUI; the remaining commands provide scriptable equivalents.
• Core (internal/core) - The business logic: managing binaries and versions, parsing GitHub URLs, extracting archives, and verifying checksums.
• Database (internal/database) - A SQLite data layer with a repository per entity. See the database reference for details.
• Providers (internal/providers) - Integrations with external sources. GitHub is currently the only supported provider.
• TUI (internal/tui) - The interactive Terminal UI, built with Bubble Tea and following the Elm Architecture (Model–Update–View).

Technology

binmate is written in Go and builds on a small set of well-known libraries:

• Cobra - CLI framework for command structure.
• Viper - Configuration management.
• Bubble Tea - Terminal UI framework.
• Lip Gloss - Terminal styling.
• SQLite - Embedded database for state persistence.