# thesubh213/winitrix architecture

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

- Interactive diagram: https://gitdiagram.com/thesubh213/winitrix
- Repository: https://github.com/thesubh213/winitrix

## Overview

Winitrix is a Go-based, Windows-first CLI that coordinates updates across many package-manager ecosystems from one entry point. The binary entrypoint is `main.go`, and the command surface is built under `cmd/` with Cobra-style subcommands and flags.

The top-level boundary is the CLI layer:
- `winitrix` runs the main update workflow.
- `doctor`, `clean`, `stats`, `logs`, `config`, `schedule`, `install`, and `version` are separate operational commands.
- Flags such as `--silent`, `--json`, `--dry-run`, `--only`, `--exclude`, and retry/timeouts alter the same core orchestration path rather than launching separate subsystems.

The core update flow lives behind `cmd/root.go` and is designed to branch into two execution modes:
- a TUI mode for interactive progress and user choice
- a silent/headless mode for non-interactive execution
Both modes use the same underlying ecosystem discovery and command execution logic, so the UI is a presentation layer, not the source of orchestration.

The main plugin boundary is `pkg/ecosystem/`. This package defines the package-manager abstraction and contains adapters for 21 ecosystems: Windows-native tools, Node.js, Python, Rust, DevOps tools, and developer utilities. Each adapter wraps a native CLI manager such as Winget, Scoop, Chocolatey, npm, pnpm, Yarn, Bun, Pip, Pipx, uv, Poetry, Conda, Cargo, Rustup, Docker, Terraform, Helm, Go tools, .NET tools, VS Code extensions, and WSL/Apt.

That ecosystem layer is responsible for detection, filtering, and execution semantics per manager. The `manager.go` interface is the key architectural seam: higher-level code can treat each ecosystem uniformly while individual adapters encapsulate manager-specific commands, capabilities, and failure modes.

Interactive progress is handled by `pkg/tui/`, which is a Bubble Tea state machine with styling via Lip Gloss. The TUI consumes orchestration events, renders progress and status, and lets the user observe or influence the update process without directly owning the update logic.

Several cross-cutting services sit between orchestration and the OS:
- `pkg/runner/` executes subprocesses and abstracts command invocation
- `pkg/elevation/` handles UAC/admin privilege escalation on Windows
- `pkg/translator/` converts raw CLI and OS errors into human-readable guidance
- `pkg/retry/` centralizes retry behavior and backoff
These packages form the execution boundary around external manager binaries and Windows privilege requirements.

Stateful behavior is kept local and file-based. `pkg/config/` reads and writes TOML configuration, `pkg/state/` persists run state, and `pkg/report/` captures structured run results, including the JSON output path described in the README. `pkg/paths/` centralizes per-user storage locations under AppData/LocalAppData, which is important because the app relies on local disk instead of any backend service.

Observability is also local and offline-first. `pkg/logger/` writes debug logs, `cmd/logs.go` exposes those logs to users, and the `logs --bundle` path packages diagnostics, config, and state for troubleshooting. This is consistent with the project’s zero-telemetry stance: data flows stay on the machine unless the user explicitly exports them.

Pre-flight health checks are isolated in `pkg/doctor/` and exposed through the `doctor` command. That subsystem focuses on environment readiness such as DNS/network checks and PATH or ecosystem health, so it acts as a diagnostic gate before running the heavier update workflow.

There are also Windows-specific operational integrations outside the main update loop:
- `cmd/install_windows.go` and `cmd/install_auto_stub.go` support user-profile installation and PATH setup
- `cmd/schedule_windows.go` and `cmd/schedule_stub.go` integrate with Windows Task Scheduler
- `pkg/notify/` provides desktop notifications on Windows
These are platform boundaries, with stub files indicating compile-time differences for unsupported or non-Windows builds.

Packaging and release are handled separately from runtime logic. The repo includes a Windows installer script under `installer/`, plus GitHub Actions workflows for build and release automation. That means the shipped artifacts are a compiled Go binary plus a Windows installer/portable distribution, not a server-deployed application.

For an architecture diagram, the most important flows are: user command → CLI parsing/config loading → ecosystem detection/filtering → runner/elevation execution against external manager CLIs → result aggregation into report/state/logs → optional TUI, JSON output, notifications, or diagnostics. The main boundaries are between CLI orchestration, per-ecosystem adapters, OS-specific services, and local persistence.

Main entry points: [`cmd/root.go`](https://github.com/thesubh213/winitrix/blob/main/cmd/root.go) (winitrix), [`pkg/ecosystem/manager.go`](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/manager.go) (manager), [`pkg/tui/model.go`](https://github.com/thesubh213/winitrix/blob/main/pkg/tui/model.go) (tui), [`pkg/doctor/doctor.go`](https://github.com/thesubh213/winitrix/blob/main/pkg/doctor/doctor.go) (doctor core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_main(("main<br/>entrypoint<br/>[main.go]"))
  node_root["winitrix<br/>orchestrator<br/>[root.go]"]
  node_doctor_cmd["doctor<br/>command<br/>[doctor.go]"]
  node_logs_cmd["logs<br/>command<br/>[logs.go]"]
end

subgraph group_core["Core flow"]
  node_tui(("tui<br/>bubble tea ui<br/>[model.go]"))
end

subgraph group_ecosystem["Ecosystems"]
  node_ecosystem_mgr["manager<br/>interface<br/>[manager.go]"]
  node_ecosystem_filter["filter<br/>selection<br/>[filter.go]"]
  node_winget["winget<br/>adapter<br/>[winget.go]"]
  node_npm["npm<br/>adapter<br/>[npm.go]"]
  node_pip["pip<br/>adapter<br/>[pip.go]"]
  node_cargo["cargo<br/>adapter<br/>[cargo.go]"]
  node_docker["docker<br/>adapter<br/>[docker.go]"]
  node_vscode["vscode<br/>adapter<br/>[vscode.go]"]
end

subgraph group_services["Services"]
  node_config_pkg["config<br/>[config.go]"]
  node_runner["runner<br/>process exec<br/>[runner.go]"]
  node_elevation["elevation<br/>uac helper<br/>[elevation.go]"]
  node_translator["translator<br/>error guidance<br/>[translator.go]"]
  node_retry["retry<br/>backoff<br/>[retry.go]"]
  node_report["report<br/>results<br/>[report.go]"]
  node_state["state<br/>[state.go]"]
  node_logger["logger<br/>debug logs<br/>[logger.go]"]
  node_doctor_pkg["doctor core<br/>health checks<br/>[doctor.go]"]
end

subgraph group_platform["Windows"]
  node_install_cmd["install<br/>command<br/>[install_windows.go]"]
  node_schedule_cmd["schedule<br/>command"]
  node_notify["notify<br/>[notify_windows.go]"]
end

subgraph group_release["Release"]
  node_installer["installer<br/>[winitrix.iss]"]
  node_release_ci["release CI<br/>github actions<br/>[release.yml]"]
end

node_main -->|"starts"| node_root
node_root -->|"loads"| node_config_pkg
node_root -->|"selects"| node_ecosystem_filter
node_root -->|"orchestrates"| node_ecosystem_mgr
node_ecosystem_mgr -->|"implemented by"| node_winget
node_ecosystem_mgr -->|"implemented by"| node_npm
node_ecosystem_mgr -->|"implemented by"| node_pip
node_ecosystem_mgr -->|"implemented by"| node_cargo
node_ecosystem_mgr -->|"implemented by"| node_docker
node_ecosystem_mgr -->|"implemented by"| node_vscode
node_root -->|"executes"| node_runner
node_root -->|"elevates"| node_elevation
node_root -->|"retries"| node_retry
node_root -->|"explains"| node_translator
node_root -->|"emits"| node_report
node_root -->|"persists"| node_state
node_root -->|"logs"| node_logger
node_root -->|"renders"| node_tui
node_root -->|"notifies"| node_notify
node_doctor_cmd -->|"invokes"| node_doctor_pkg
node_logs_cmd -->|"reads"| node_logger
node_install_cmd -->|"uses"| node_elevation
node_schedule_cmd -->|"integrates"| node_notify
node_doctor_pkg -->|"probes"| node_runner
node_doctor_pkg -->|"maps"| node_translator
node_tui -->|"consumes"| node_report
node_tui -->|"observes"| node_ecosystem_filter
node_installer -->|"shipped by"| node_release_ci

click node_main "https://github.com/thesubh213/winitrix/blob/main/main.go"
click node_root "https://github.com/thesubh213/winitrix/blob/main/cmd/root.go"
click node_doctor_cmd "https://github.com/thesubh213/winitrix/blob/main/cmd/doctor.go"
click node_logs_cmd "https://github.com/thesubh213/winitrix/blob/main/cmd/logs.go"
click node_install_cmd "https://github.com/thesubh213/winitrix/blob/main/cmd/install_windows.go"
click node_schedule_cmd "https://github.com/thesubh213/winitrix/blob/main/cmd/schedule_windows.go"
click node_config_pkg "https://github.com/thesubh213/winitrix/blob/main/pkg/config/config.go"
click node_ecosystem_mgr "https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/manager.go"
click node_ecosystem_filter "https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/filter.go"
click node_winget "https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/winget.go"
click node_npm "https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/npm.go"
click node_pip "https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/pip.go"
click node_cargo "https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/cargo.go"
click node_docker "https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/docker.go"
click node_vscode "https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/vscode.go"
click node_runner "https://github.com/thesubh213/winitrix/blob/main/pkg/runner/runner.go"
click node_elevation "https://github.com/thesubh213/winitrix/blob/main/pkg/elevation/elevation.go"
click node_translator "https://github.com/thesubh213/winitrix/blob/main/pkg/translator/translator.go"
click node_retry "https://github.com/thesubh213/winitrix/blob/main/pkg/retry/retry.go"
click node_report "https://github.com/thesubh213/winitrix/blob/main/pkg/report/report.go"
click node_state "https://github.com/thesubh213/winitrix/blob/main/pkg/state/state.go"
click node_logger "https://github.com/thesubh213/winitrix/blob/main/pkg/logger/logger.go"
click node_doctor_pkg "https://github.com/thesubh213/winitrix/blob/main/pkg/doctor/doctor.go"
click node_tui "https://github.com/thesubh213/winitrix/blob/main/pkg/tui/model.go"
click node_notify "https://github.com/thesubh213/winitrix/blob/main/pkg/notify/notify_windows.go"
click node_installer "https://github.com/thesubh213/winitrix/blob/main/installer/winitrix.iss"
click node_release_ci "https://github.com/thesubh213/winitrix/blob/main/.github/workflows/release.yml"

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,node_root,node_doctor_cmd,node_logs_cmd toneBlue
class node_tui toneAmber
class node_ecosystem_mgr,node_ecosystem_filter,node_winget,node_npm,node_pip,node_cargo,node_docker,node_vscode toneMint
class node_config_pkg,node_runner,node_elevation,node_translator,node_retry,node_report,node_state,node_logger,node_doctor_pkg toneRose
class node_install_cmd,node_schedule_cmd,node_notify toneIndigo
class node_installer,node_release_ci toneTeal
```

## Components

### CLI

Command surface and top-level orchestration

- [main](https://github.com/thesubh213/winitrix/blob/main/main.go): entrypoint · Program entrypoint · `main.go`
- [winitrix](https://github.com/thesubh213/winitrix/blob/main/cmd/root.go): orchestrator · Main update command and flag parsing · `cmd/root.go`
- [doctor](https://github.com/thesubh213/winitrix/blob/main/cmd/doctor.go): command · Environment readiness checks · `cmd/doctor.go`
- [logs](https://github.com/thesubh213/winitrix/blob/main/cmd/logs.go): command · Log viewing and bundling · `cmd/logs.go`

### Core flow

Update orchestration, execution, and result handling

- [tui](https://github.com/thesubh213/winitrix/blob/main/pkg/tui/model.go): bubble tea ui · Interactive progress and control surface · `pkg/tui/model.go`

### Ecosystems

Package-manager abstraction and adapters

- [manager](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/manager.go): interface · Common package-manager contract · `pkg/ecosystem/manager.go`
- [filter](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/filter.go): selection · Ecosystem detection and targeting · `pkg/ecosystem/filter.go`
- [winget](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/winget.go): adapter · Windows package manager adapter · `pkg/ecosystem/winget.go`
- [npm](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/npm.go): adapter · Node ecosystem adapter · `pkg/ecosystem/npm.go`
- [pip](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/pip.go): adapter · Python ecosystem adapter · `pkg/ecosystem/pip.go`
- [cargo](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/cargo.go): adapter · Rust ecosystem adapter · `pkg/ecosystem/cargo.go`
- [docker](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/docker.go): adapter · DevOps tool adapter · `pkg/ecosystem/docker.go`
- [vscode](https://github.com/thesubh213/winitrix/blob/main/pkg/ecosystem/vscode.go): adapter · Developer tool adapter · `pkg/ecosystem/vscode.go`

### Services

Cross-cutting execution and local persistence

- [config](https://github.com/thesubh213/winitrix/blob/main/pkg/config/config.go): toml config · Reads and writes user settings · `pkg/config/config.go`
- [runner](https://github.com/thesubh213/winitrix/blob/main/pkg/runner/runner.go): process exec · Subprocess invocation boundary · `pkg/runner/runner.go`
- [elevation](https://github.com/thesubh213/winitrix/blob/main/pkg/elevation/elevation.go): uac helper · Windows privilege escalation · `pkg/elevation/elevation.go`
- [translator](https://github.com/thesubh213/winitrix/blob/main/pkg/translator/translator.go): error guidance · Turns raw failures into user-facing guidance · `pkg/translator/translator.go`
- [retry](https://github.com/thesubh213/winitrix/blob/main/pkg/retry/retry.go): backoff · Central retry policy · `pkg/retry/retry.go`
- [report](https://github.com/thesubh213/winitrix/blob/main/pkg/report/report.go): results · Structured run results and JSON output · `pkg/report/report.go`
- [state](https://github.com/thesubh213/winitrix/blob/main/pkg/state/state.go): local state · Persisted run state · `pkg/state/state.go`
- [logger](https://github.com/thesubh213/winitrix/blob/main/pkg/logger/logger.go): debug logs · Local debug logging · `pkg/logger/logger.go`
- [doctor core](https://github.com/thesubh213/winitrix/blob/main/pkg/doctor/doctor.go): health checks · Network, PATH, and environment diagnostics · `pkg/doctor/doctor.go`

### Windows

Windows-specific operations and integrations

- [install](https://github.com/thesubh213/winitrix/blob/main/cmd/install_windows.go): command · User-profile install and PATH setup · `cmd/install_windows.go`
- [schedule](https://github.com/thesubh213/winitrix/blob/main/cmd/schedule_windows.go): command · Task Scheduler integration · `cmd/schedule_windows.go`
- [notify](https://github.com/thesubh213/winitrix/blob/main/pkg/notify/notify_windows.go): desktop notify · Windows desktop notifications · `pkg/notify/notify_windows.go`

### Release

Packaging and CI automation

- [installer](https://github.com/thesubh213/winitrix/blob/main/installer/winitrix.iss): windows installer · Windows installer script · `installer/winitrix.iss`
- [release CI](https://github.com/thesubh213/winitrix/blob/main/.github/workflows/release.yml): github actions · Build and release automation · `.github/workflows/release.yml`

## Connections

- main → winitrix: starts · Binary entrypoint hands control to CLI orchestration
- winitrix → config: loads · CLI bootstraps user configuration
- winitrix → filter: selects · Chooses which ecosystems participate in a run
- winitrix → manager: orchestrates · Top-level workflow uses the common manager contract
- manager → winget: implemented by · Representative ecosystem adapters implement the interface
- manager → npm: implemented by · Representative ecosystem adapters implement the interface
- manager → pip: implemented by · Representative ecosystem adapters implement the interface
- manager → cargo: implemented by · Representative ecosystem adapters implement the interface
- manager → docker: implemented by · Representative ecosystem adapters implement the interface
- manager → vscode: implemented by · Representative ecosystem adapters implement the interface
- winitrix → runner: executes · All external manager commands go through the process runner
- winitrix → elevation: elevates · Windows privilege escalation when required
- winitrix → retry: retries · Shared retry and backoff behavior
- winitrix → translator: explains · Converts low-level failures into guidance
- winitrix → report: emits · Aggregates structured results and JSON output
- winitrix → state: persists · Stores run state locally
- winitrix → logger: logs · Writes local debug logs
- winitrix → tui: renders · Interactive mode presents orchestration progress
- winitrix → notify: notifies · Optional Windows desktop notifications
- doctor → doctor core: invokes · Doctor command delegates to diagnostics subsystem
- logs → logger: reads · Log command surfaces local diagnostics
- install → elevation: uses · Installer path may require admin rights
- schedule → notify: integrates · Scheduled runs can surface notifications
- doctor core → runner: probes · Diagnostics may run external checks
- doctor core → translator: maps · Diagnostics turn failures into readable guidance
- tui → report: consumes · UI consumes orchestration progress and results
- tui → filter: observes · Interactive flow reflects selected ecosystems
- installer → release CI: shipped by · Installer is built and published via release automation
