# hzqtc/taproom architecture

> Architecture diagram of the GitHub repository hzqtc/taproom, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hzqtc/taproom
- Repository: https://github.com/hzqtc/taproom

## Overview

#### Purpose and Entry Point
`taproom` is a Go terminal UI for browsing and managing Homebrew formulae and casks. It consolidates package metadata, local installation state, dependency relationships, and selected operational commands into an interactive Bubble Tea application. Process startup is `main.go`, with application state and event handling centered in `internal/model/model.go`.

#### CLI and Application Bootstrap
`main.go` parses runtime flags such as cache invalidation, release fetching, hidden columns, initial filters/sort, help visibility, timer display, and theme selection. It initializes the loading/application flow and starts the Bubble Tea runtime. Key bindings and root model behavior are defined in `internal/model/keys.go` and `internal/model/model.go`; root rendering is in `internal/model/view.go`.

#### Homebrew Integration Boundary
`internal/brew` encapsulates all interaction with the local `brew` executable and Homebrew-derived data. `internal/brew/command.go` executes brew operations; `internal/brew/api.go` obtains package catalog/API data; `internal/brew/installation.go` derives installed, outdated, pinned, explicit/dependency-installed, and disk-use state. `internal/brew/tap.go` handles tap metadata. This package is the boundary between the TUI/domain layers and external Homebrew CLI/API behavior.

#### Package Domain and Enrichment
`internal/data/package.go` defines the package-level data representation used throughout the UI and derives relationships needed for display. The system combines formula/cask catalog data with local installation information, recursive missing dependencies, reverse dependents, popularity, and optional release metadata. Release enrichment is delegated to `internal/gh/gh.go`, which invokes the optional GitHub CLI and is enabled by `--fetch-release`.

#### Loading and Data Assembly
`internal/loading/loading.go` orchestrates startup data acquisition, likely issuing independent Homebrew/local-data loading tasks concurrently so slower optional columns can be suppressed via `--hide-columns`. It supplies loading progress to the UI before handing assembled package data to the main model. `internal/ui/loadingscreen.go` presents this staged initialization, including the optional load timer.

#### Interactive TUI Composition
The presentation layer is split into focused Bubble Tea/Bubbles components under `internal/ui`. `internal/ui/packagetable.go` renders and navigates the package overview; `internal/ui/details.go` renders the selected package’s metadata and dependency/dependent information. `internal/ui/searchinput.go`, `internal/ui/filter.go`, and `internal/ui/filterview.go` implement real-time query and filter state. `internal/ui/column.go` and `internal/ui/stats.go` support sortable/tabular package presentation and aggregate status display.

#### Primary Control Flow
Startup flows from `main.go` to loading orchestration, then into the Bubble Tea model with a complete package dataset. User keystrokes flow through `internal/model/keys.go` and model update logic, mutating selection, search, filters, sorting, and views. The model recomputes the visible package set and delegates rendering to UI components. Mutating actions—install, uninstall, upgrade, pin, unpin—cross back through `internal/brew/command.go`, after which application state must be refreshed or reconciled.

#### Runtime Dependencies
The binary runs locally in a terminal with Go-built Bubble Tea, Bubbles, and Lip Gloss UI libraries. Required external executables/services are Homebrew (`brew`) and `du`; GitHub CLI (`gh`) is optional for release lookup. Homebrew’s package/API data and GitHub release information are the material remote data sources.

Main entry points: [`internal/loading/loading.go`](https://github.com/hzqtc/taproom/blob/main/internal/loading/loading.go) (Loading orchestration), [`internal/model/model.go`](https://github.com/hzqtc/taproom/blob/main/internal/model/model.go) (Root model), [`internal/model/view.go`](https://github.com/hzqtc/taproom/blob/main/internal/model/view.go) (Root rendering), [`internal/data/package.go`](https://github.com/hzqtc/taproom/blob/main/internal/data/package.go) (Package domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["CLI bootstrap<br/>Go entry point<br/>[main.go]"]
end

subgraph group_loading["Loading &amp; Data"]
  node_loading_orchestrator["Loading orchestration<br/>startup pipeline<br/>[loading.go]"]
  node_loading_screen["Loading screen<br/>Bubble Tea component<br/>[loadingscreen.go]"]
  node_package_domain["Package domain<br/>package model<br/>[package.go]"]
  node_brew_api["Catalog API<br/>Homebrew data adapter<br/>[api.go]"]
  node_installation["Installation state<br/>local-state adapter<br/>[installation.go]"]
  node_tap["Tap metadata<br/>Homebrew adapter<br/>[tap.go]"]
  node_release_lookup["Release enrichment<br/>GitHub adapter<br/>[gh.go]"]
end

subgraph group_tui["Interactive TUI"]
  node_model["Root model<br/>Bubble Tea model<br/>[model.go]"]
  node_keys["Key bindings<br/>input mapping<br/>[keys.go]"]
  node_root_view["Root rendering<br/>view composition<br/>[view.go]"]
  node_package_table["Package table<br/>Bubble Tea component<br/>[packagetable.go]"]
  node_details["Package details<br/>Bubble Tea component<br/>[details.go]"]
  node_search["Search and filters<br/>Bubble Tea components<br/>[searchinput.go]"]
  node_filter_view["Filter view<br/>Bubble Tea component<br/>[filterview.go]"]
  node_table_support["Columns and stats<br/>table components<br/>[column.go]"]
end

subgraph group_external["External Tools &amp; Data"]
  node_brew_commands["Brew commands<br/>command adapter<br/>[command.go]"]
  node_brew{{"Homebrew<br/>local executable and API"}}
  node_du{{"du<br/>local executable"}}
  node_gh{{"GitHub CLI<br/>optional executable"}}
end

node_main -->|"starts"| node_loading_orchestrator
node_main -->|"launches"| node_model
node_loading_orchestrator -->|"reports progress"| node_loading_screen
node_loading_orchestrator -->|"loads catalog"| node_brew_api
node_loading_orchestrator -->|"loads local state"| node_installation
node_loading_orchestrator -->|"loads taps"| node_tap
node_loading_orchestrator -.->|"optional release load"| node_release_lookup
node_brew_api -->|"queries"| node_brew
node_installation -->|"inspects"| node_brew
node_installation -->|"measures"| node_du
node_tap -->|"queries"| node_brew
node_release_lookup -.->|"invokes"| node_gh
node_brew_api -->|"catalog data"| node_package_domain
node_installation -->|"installation data"| node_package_domain
node_tap -->|"tap data"| node_package_domain
node_release_lookup -.->|"release data"| node_package_domain
node_package_domain -->|"assembled dataset"| node_model
node_keys -->|"maps input"| node_model
node_model -->|"renders"| node_root_view
node_root_view -->|"composes"| node_package_table
node_root_view -->|"composes"| node_details
node_root_view -->|"composes"| node_search
node_root_view -->|"composes"| node_filter_view
node_package_table -->|"uses"| node_table_support
node_model -->|"mutating actions"| node_brew_commands
node_brew_commands -->|"executes"| node_brew
node_brew_commands -.->|"refreshes state"| node_model

click node_main "https://github.com/hzqtc/taproom/blob/main/main.go"
click node_model "https://github.com/hzqtc/taproom/blob/main/internal/model/model.go"
click node_keys "https://github.com/hzqtc/taproom/blob/main/internal/model/keys.go"
click node_root_view "https://github.com/hzqtc/taproom/blob/main/internal/model/view.go"
click node_loading_orchestrator "https://github.com/hzqtc/taproom/blob/main/internal/loading/loading.go"
click node_loading_screen "https://github.com/hzqtc/taproom/blob/main/internal/ui/loadingscreen.go"
click node_package_domain "https://github.com/hzqtc/taproom/blob/main/internal/data/package.go"
click node_brew_api "https://github.com/hzqtc/taproom/blob/main/internal/brew/api.go"
click node_installation "https://github.com/hzqtc/taproom/blob/main/internal/brew/installation.go"
click node_tap "https://github.com/hzqtc/taproom/blob/main/internal/brew/tap.go"
click node_release_lookup "https://github.com/hzqtc/taproom/blob/main/internal/gh/gh.go"
click node_package_table "https://github.com/hzqtc/taproom/blob/main/internal/ui/packagetable.go"
click node_details "https://github.com/hzqtc/taproom/blob/main/internal/ui/details.go"
click node_search "https://github.com/hzqtc/taproom/blob/main/internal/ui/searchinput.go"
click node_filter_view "https://github.com/hzqtc/taproom/blob/main/internal/ui/filterview.go"
click node_table_support "https://github.com/hzqtc/taproom/blob/main/internal/ui/column.go"
click node_brew_commands "https://github.com/hzqtc/taproom/blob/main/internal/brew/command.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main toneBlue
class node_loading_orchestrator,node_loading_screen,node_package_domain,node_brew_api,node_installation,node_tap,node_release_lookup toneAmber
class node_model,node_keys,node_root_view,node_package_table,node_details,node_search,node_filter_view,node_table_support toneMint
class node_brew_commands,node_brew,node_du,node_gh toneRose
```

## Components

### Runtime

- [CLI bootstrap](https://github.com/hzqtc/taproom/blob/main/main.go): Go entry point · Parses flags and starts the Bubble Tea application. · `main.go`

### Loading & Data

- [Loading orchestration](https://github.com/hzqtc/taproom/blob/main/internal/loading/loading.go): startup pipeline · Assembles package data and reports staged loading progress. · `internal/loading/loading.go`
- [Loading screen](https://github.com/hzqtc/taproom/blob/main/internal/ui/loadingscreen.go): Bubble Tea component · Shows initialization stages and optional timer. · `internal/ui/loadingscreen.go`
- [Package domain](https://github.com/hzqtc/taproom/blob/main/internal/data/package.go): package model · Combines catalog, installation, relationships, popularity, and releases. · `internal/data/package.go`
- [Catalog API](https://github.com/hzqtc/taproom/blob/main/internal/brew/api.go): Homebrew data adapter · `internal/brew/api.go`
- [Installation state](https://github.com/hzqtc/taproom/blob/main/internal/brew/installation.go): local-state adapter · Derives installed, outdated, pinned, dependency, and disk-use state. · `internal/brew/installation.go`
- [Tap metadata](https://github.com/hzqtc/taproom/blob/main/internal/brew/tap.go): Homebrew adapter · `internal/brew/tap.go`
- [Release enrichment](https://github.com/hzqtc/taproom/blob/main/internal/gh/gh.go): GitHub adapter · Optional enrichment enabled by --fetch-release. · `internal/gh/gh.go`

### Interactive TUI

- [Root model](https://github.com/hzqtc/taproom/blob/main/internal/model/model.go): Bubble Tea model · Owns application state, updates, and visible-package recomputation. · `internal/model/model.go`
- [Key bindings](https://github.com/hzqtc/taproom/blob/main/internal/model/keys.go): input mapping · `internal/model/keys.go`
- [Root rendering](https://github.com/hzqtc/taproom/blob/main/internal/model/view.go): view composition · `internal/model/view.go`
- [Package table](https://github.com/hzqtc/taproom/blob/main/internal/ui/packagetable.go): Bubble Tea component · Navigable, sortable package overview. · `internal/ui/packagetable.go`
- [Package details](https://github.com/hzqtc/taproom/blob/main/internal/ui/details.go): Bubble Tea component · Shows selected metadata, dependencies, and dependents. · `internal/ui/details.go`
- [Search and filters](https://github.com/hzqtc/taproom/blob/main/internal/ui/searchinput.go): Bubble Tea components · Maintains real-time query and filter state. · `internal/ui/searchinput.go`
- [Filter view](https://github.com/hzqtc/taproom/blob/main/internal/ui/filterview.go): Bubble Tea component · `internal/ui/filterview.go`
- [Columns and stats](https://github.com/hzqtc/taproom/blob/main/internal/ui/column.go): table components · Supports column presentation and aggregate status. · `internal/ui/column.go`

### External Tools & Data

- [Brew commands](https://github.com/hzqtc/taproom/blob/main/internal/brew/command.go): command adapter · Executes install, uninstall, upgrade, pin, and unpin operations. · `internal/brew/command.go`
- **Homebrew**: local executable and API · Provides catalog, tap, and local package state.
- **du**: local executable · Supplies disk-use measurements.
- **GitHub CLI**: optional executable · Retrieves release metadata.

## Connections

- CLI bootstrap → Loading orchestration: starts
- CLI bootstrap → Root model: launches
- Loading orchestration → Loading screen: reports progress
- Loading orchestration → Catalog API: loads catalog
- Loading orchestration → Installation state: loads local state
- Loading orchestration → Tap metadata: loads taps
- Loading orchestration → Release enrichment: optional release load
- Catalog API → Homebrew: queries
- Installation state → Homebrew: inspects
- Installation state → du: measures
- Tap metadata → Homebrew: queries
- Release enrichment → GitHub CLI: invokes
- Catalog API → Package domain: catalog data
- Installation state → Package domain: installation data
- Tap metadata → Package domain: tap data
- Release enrichment → Package domain: release data
- Package domain → Root model: assembled dataset
- Key bindings → Root model: maps input
- Root model → Root rendering: renders
- Root rendering → Package table: composes
- Root rendering → Package details: composes
- Root rendering → Search and filters: composes
- Root rendering → Filter view: composes
- Package table → Columns and stats: uses
- Root model → Brew commands: mutating actions
- Brew commands → Homebrew: executes
- Brew commands → Root model: refreshes state