# frankea/whisky architecture

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

- Interactive diagram: https://gitdiagram.com/frankea/whisky
- Repository: https://github.com/frankea/whisky

## Overview

1. **Overall shape**
   - Whisky is a macOS Swift/SwiftUI application with a shared core library, plus two auxiliary targets: a command-line tool (`WhiskyCmd`) and a Finder thumbnail extension (`WhiskyThumbnail`).
   - The main architectural boundary is between the **UI/app layer** in `Whisky/` and the **domain/runtime layer** in `WhiskyKit/`.

2. **Primary runtime responsibility**
   - The app is a Wine wrapper for macOS: it creates and manages “bottles,” configures them, installs a bundled Wine runtime, and launches Windows programs and games inside those bottles.
   - Almost all non-UI logic lives in `WhiskyKit`, which is reused by the app UI, CLI, and tests.

3. **UI layer**
   - `Whisky/Views/` is a large SwiftUI surface split by workflow: setup, bottles, programs, game database, diagnostics, audio, troubleshooting, settings, menus, and common components.
   - `Whisky/Views/WhiskyApp.swift` and `AppDelegate.swift` are the app entry points; view models such as `BottleVM` and `ProcessesViewModel` bridge the UI to the core model/state.

4. **Core domain model**
   - `WhiskyKit/Sources/WhiskyKit/Whisky/` contains the central models: `Bottle`, `Program`, `RunLog`, bottle settings/config structs, shortcut creation, legacy import, and launch result types.
   - This layer represents the persisted user state and bottle-specific configuration, and it is the main source of truth for the app.

5. **Wine execution and environment setup**
   - `WhiskyKit/Sources/WhiskyKit/Wine/` builds the execution environment for Wine, detects GPU/backend capabilities, resolves graphics backend choices, manages Wine processes, and handles registry/environment interactions.
   - `EnvironmentBuilder`, `WineEnvironment`, `WineRegistry`, and related types form the launch pipeline from bottle settings to a runnable Windows process.

6. **Runtime installation and dependency management**
   - `WhiskyKit/Sources/WhiskyKit/WhiskyWine/` handles downloading, validating, and installing the bundled Whisky Wine runtime.
   - `Whisky/Utils/DependencyManager.swift`, `Winetricks.swift`, and related setup views coordinate additional dependencies and first-run setup, making the runtime-install path a distinct startup flow.

7. **Bottle configuration and per-app overrides**
   - Bottle configuration is decomposed into separate concerns: graphics, audio, input, launcher, performance, Metal/DXVK/DXMT, cleanup, and Wine-specific settings.
   - `Program` and `ProgramOverrides` provide per-application overrides so different Windows executables can have different launch behavior inside the same bottle.

8. **Game compatibility subsystem**
   - `WhiskyKit/Sources/WhiskyKit/GameDatabase/` loads a curated JSON database of game-specific configurations, matches installed apps to entries, and applies configuration snapshots.
   - The UI surfaces this through the GameDB views, letting users preview and apply recommended settings rather than manually tuning bottles.

9. **Diagnostics and troubleshooting pipeline**
   - The diagnostics subsystem classifies crashes and produces redacted exportable reports from logs and prefix state.
   - A separate troubleshooting engine in `WhiskyKit/Sources/WhiskyKit/Troubleshooting/` drives scripted flows made of checks, preflight collection, and fix applicators; the SwiftUI wizard is just the presentation layer over that engine.

10. **Audio and controller support**
   - Audio has its own subsystem for probing devices, tracking changes, testing output, and diagnosing Wine audio issues.
   - Controller support is handled through bottle configuration and diagnostics around input/device setup, reflecting that gamepad/input problems are a first-class concern.

11. **Binary/file-format tooling**
   - `WhiskyKit` includes PE parsing, icon/resource extraction, ShellLink handling, tar handling, temporary file tracking, and clipboard/process utilities.
   - These support file discovery, shortcut creation, icon rendering, and binary inspection rather than being core business logic.

12. **Persistence and local data boundaries**
   - User data is stored locally in macOS container/support locations: bottles, cached runtime files, logs, preferences, and diagnostic history live under the app’s container/support directories.
   - Migration support exists for importing bottles from the archived original Whisky bundle identifier, but bottles remain file-system-backed and are not centralized in a server.

13. **External services and distribution**
   - Updates are delivered via **Sparkle** using a hosted appcast; runtime artifacts and releases are distributed through GitHub-hosted release infrastructure and Homebrew casks/taps.
   - Optional telemetry is sent to a third-party analytics service only when enabled, and is limited to a small set of first-run funnel events.

14. **Build, test, and packaging structure**
   - `WhiskyKit` is a standalone Swift package with extensive unit tests; the app target and extension targets consume it as the shared core.
   - CI, release, and packaging scripts assemble the macOS app, runtime assets, docs, and distribution artifacts, while UI tests cover the SwiftUI surface separately from the package tests.

Main entry points: [`WhiskyKit/Sources/WhiskyKit/Whisky`](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Whisky) (Domain Model), [`WhiskyKit/Sources/WhiskyKit/Wine`](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Wine) (Wine Runtime), [`WhiskyKit/Sources/WhiskyKit/Troubleshooting`](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Troubleshooting) (Troubleshooting), [`Whisky/Views/WhiskyApp.swift`](https://github.com/frankea/whisky/blob/main/Whisky/Views/WhiskyApp.swift) (Whisky)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App & UI"]
  node_whisky_app["Whisky<br/>macOS app<br/>[WhiskyApp.swift]"]
  node_app_delegate["App Delegate<br/>app entry<br/>[AppDelegate.swift]"]
  node_ui_views["Views<br/>swiftui surface"]
  node_view_models["View Models<br/>ui bridge"]
  node_app_utils["App Utils<br/>app services"]
  node_cmd_tool["WhiskyCmd<br/>cli tool<br/>[Main.swift]"]
  node_thumb_ext["Thumbnail<br/>finder extension"]
end

subgraph group_core["WhiskyKit"]
  node_kit_whisky["Domain Model<br/>core state"]
  node_kit_wine["Wine Runtime<br/>launch env"]
  node_kit_runtime["WhiskyWine<br/>runtime installer"]
  node_kit_gamedb["Game DB<br/>compatibility data"]
  node_kit_trouble["Troubleshooting<br/>scripted flows"]
  node_kit_diagnostics["Diagnostics<br/>crash analysis"]
  node_kit_audio["Audio"]
  node_kit_binary["Binary Tools<br/>file tooling"]
  node_kit_utils["Core Utils<br/>support utils"]
  node_tests["Tests"]
end

subgraph group_ops["Build & Distribution"]
  node_ci["CI & Release<br/>automation<br/>[CI.yml]"]
  node_dist_site["Dist Pages<br/>release assets<br/>[appcast.xml]"]
end

node_whisky_app -->|"boots"| node_app_delegate
node_whisky_app -->|"hosts"| node_ui_views
node_whisky_app -->|"binds"| node_view_models
node_ui_views -->|"uses"| node_view_models
node_view_models -->|"reads/writes"| node_kit_whisky
node_app_utils -->|"orchestrates"| node_kit_whisky
node_cmd_tool -->|"calls"| node_kit_whisky
node_thumb_ext -->|"renders"| node_kit_binary
node_kit_whisky -->|"launches via"| node_kit_wine
node_kit_whisky -->|"installs"| node_kit_runtime
node_kit_whisky -->|"applies"| node_kit_gamedb
node_kit_whisky -->|"diagnoses"| node_kit_trouble
node_kit_whisky -->|"exports"| node_kit_diagnostics
node_kit_whisky -->|"configures"| node_kit_audio
node_kit_wine -->|"probes"| node_kit_audio
node_kit_wine -->|"uses"| node_kit_binary
node_kit_trouble -->|"consumes"| node_kit_diagnostics
node_kit_trouble -->|"checks"| node_kit_gamedb
node_kit_runtime -->|"packs"| node_ci
node_ci -->|"publishes"| node_dist_site
node_tests -->|"covers"| node_kit_whisky
node_tests -->|"covers"| node_kit_wine
node_tests -->|"covers"| node_kit_trouble

click node_whisky_app "https://github.com/frankea/whisky/blob/main/Whisky/Views/WhiskyApp.swift"
click node_app_delegate "https://github.com/frankea/whisky/blob/main/Whisky/AppDelegate.swift"
click node_ui_views "https://github.com/frankea/whisky/tree/main/Whisky/Views"
click node_view_models "https://github.com/frankea/whisky/tree/main/Whisky/View Models"
click node_app_utils "https://github.com/frankea/whisky/tree/main/Whisky/Utils"
click node_cmd_tool "https://github.com/frankea/whisky/blob/main/WhiskyCmd/Main.swift"
click node_thumb_ext "https://github.com/frankea/whisky/blob/main/WhiskyThumbnail/ThumbnailProvider.swift"
click node_kit_whisky "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Whisky"
click node_kit_wine "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Wine"
click node_kit_runtime "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/WhiskyWine"
click node_kit_gamedb "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/GameDatabase"
click node_kit_trouble "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Troubleshooting"
click node_kit_diagnostics "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Diagnostics"
click node_kit_audio "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Audio"
click node_kit_binary "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/PE"
click node_kit_utils "https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Utils"
click node_tests "https://github.com/frankea/whisky/tree/main/WhiskyKit/Tests/WhiskyKitTests"
click node_ci "https://github.com/frankea/whisky/blob/main/.github/workflows/CI.yml"
click node_dist_site "https://github.com/frankea/whisky/blob/main/dist/pages/appcast.xml"

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_whisky_app,node_app_delegate,node_ui_views,node_view_models,node_app_utils,node_cmd_tool,node_thumb_ext toneBlue
class node_kit_whisky,node_kit_wine,node_kit_runtime,node_kit_gamedb,node_kit_trouble,node_kit_diagnostics,node_kit_audio,node_kit_binary,node_kit_utils,node_tests toneAmber
class node_ci,node_dist_site toneMint
```

## Components

### App & UI

macOS app, SwiftUI surface, and auxiliary targets.

- [Whisky](https://github.com/frankea/whisky/blob/main/Whisky/Views/WhiskyApp.swift): macOS app · Main SwiftUI application target and user-facing shell. · `Whisky/Views/WhiskyApp.swift`
- [App Delegate](https://github.com/frankea/whisky/blob/main/Whisky/AppDelegate.swift): app entry · Lifecycle, setup, and app integration glue. · `Whisky/AppDelegate.swift`
- [Views](https://github.com/frankea/whisky/tree/main/Whisky/Views): swiftui surface · Primary UI workflows for bottles, setup, diagnostics, games, settings, and troubleshooting. · `Whisky/Views`
- [View Models](https://github.com/frankea/whisky/tree/HEAD/Whisky/View%20Models): ui bridge · State adapters between SwiftUI and shared core models. · `Whisky/View Models`
- [App Utils](https://github.com/frankea/whisky/tree/main/Whisky/Utils): app services · UI-adjacent helpers for updates, telemetry, dependency install, launcher detection, and command launching. · `Whisky/Utils`
- [WhiskyCmd](https://github.com/frankea/whisky/blob/main/WhiskyCmd/Main.swift): cli tool · Command-line entry point for scripting and automation. · `WhiskyCmd/Main.swift`
- [Thumbnail](https://github.com/frankea/whisky/blob/main/WhiskyThumbnail/ThumbnailProvider.swift): finder extension · Finder thumbnail provider for Whisky-related file previews. · `WhiskyThumbnail/ThumbnailProvider.swift`

### WhiskyKit

Shared domain, runtime, and tooling library.

- [Domain Model](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Whisky): core state · Bottles, programs, settings, run logs, shortcuts, imports, and launch results. · `WhiskyKit/Sources/WhiskyKit/Whisky`
- [Wine Runtime](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Wine): launch env · Builds Wine execution environment, backend selection, registry access, and process management. · `WhiskyKit/Sources/WhiskyKit/Wine`
- [WhiskyWine](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/WhiskyWine): runtime installer · Downloads, validates, and installs the bundled Whisky Wine runtime. · `WhiskyKit/Sources/WhiskyKit/WhiskyWine`
- [Game DB](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/GameDatabase): compatibility data · Loads game-specific configs, matches installed apps, and applies recommended settings. · `WhiskyKit/Sources/WhiskyKit/GameDatabase`
- [Troubleshooting](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Troubleshooting): scripted flows · Checks, preflight collection, flow execution, fix application, and history storage. · `WhiskyKit/Sources/WhiskyKit/Troubleshooting`
- [Diagnostics](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Diagnostics): crash analysis · Crash classification, redaction, export, and remediation mapping. · `WhiskyKit/Sources/WhiskyKit/Diagnostics`
- [Audio](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Audio): audio probe · Audio device monitoring, probing, status tracking, and Wine audio troubleshooting. · `WhiskyKit/Sources/WhiskyKit/Audio`
- [Binary Tools](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/PE): file tooling · PE parsing, icon/resource extraction, ShellLink handling, tar, temp files, and process/clipboard helpers. · `WhiskyKit/Sources/WhiskyKit/PE`
- [Core Utils](https://github.com/frankea/whisky/tree/main/WhiskyKit/Sources/WhiskyKit/Utils): support utils · Host architecture, Rosetta, terminal integration, and stability diagnostics helpers. · `WhiskyKit/Sources/WhiskyKit/Utils`
- [Tests](https://github.com/frankea/whisky/tree/main/WhiskyKit/Tests/WhiskyKitTests): package tests · Shared unit tests for the WhiskyKit package and its subsystems. · `WhiskyKit/Tests/WhiskyKitTests`

### Build & Distribution

CI, packaging, releases, and hosted artifacts.

- [CI & Release](https://github.com/frankea/whisky/blob/main/.github/workflows/CI.yml): automation · Workflows and scripts for build, release, update feeds, scanning, and packaging. · `.github/workflows/CI.yml`
- [Dist Pages](https://github.com/frankea/whisky/blob/main/dist/pages/appcast.xml): release assets · Hosted appcast and distribution pages for updates and release metadata. · `dist/pages/appcast.xml`

## Connections

- Whisky → App Delegate: boots · App entry initializes lifecycle and services.
- Whisky → Views: hosts · Main window and workflow navigation are built from SwiftUI views.
- Whisky → View Models: binds · View models mediate state between UI and core models.
- Views → View Models: uses · Screens consume shared observable state and actions.
- View Models → Domain Model: reads/writes · UI state is backed by bottles, programs, and settings.
- App Utils → Domain Model: orchestrates · Setup, shortcuts, telemetry, and launch helpers act on core state.
- WhiskyCmd → Domain Model: calls · CLI uses the shared domain and runtime APIs.
- Thumbnail → Binary Tools: renders · Thumbnail generation relies on binary/icon extraction helpers.
- Domain Model → Wine Runtime: launches via · Bottle and program state drive Wine environment setup and execution.
- Domain Model → WhiskyWine: installs · Shared model includes bundled runtime install and version state.
- Domain Model → Game DB: applies · Game configurations can be matched and applied to bottles.
- Domain Model → Troubleshooting: diagnoses · Troubleshooting flows operate on bottle and prefix state.
- Domain Model → Diagnostics: exports · Run logs and crash data feed diagnostic classification and export.
- Domain Model → Audio: configures · Audio settings and device state are part of bottle configuration.
- Wine Runtime → Audio: probes · Wine audio helpers interact with device probing and tests.
- Wine Runtime → Binary Tools: uses · Execution helpers depend on process, file, and binary utilities.
- Troubleshooting → Diagnostics: consumes · Troubleshooting flows use diagnostics and preflight evidence.
- Troubleshooting → Game DB: checks · Some flows validate whether a compatible game configuration exists.
- WhiskyWine → CI & Release: packs · Release automation assembles runtime artifacts and app bundles.
- CI & Release → Dist Pages: publishes · Release workflows generate appcast and hosted distribution pages.
- Tests → Domain Model: covers · Package tests exercise the core domain model and launch behavior.
- Tests → Wine Runtime: covers · Tests validate environment building, GPU detection, and prefix behavior.
- Tests → Troubleshooting: covers · Troubleshooting flows and checks are verified by unit tests.
