# tfourj/earie architecture

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

- Interactive diagram: https://gitdiagram.com/tfourj/earie
- Repository: https://github.com/tfourj/earie

## Overview

1. **What this repo is**
   - Earie is a **Windows per-app audio mixer** built with **C++/Qt 6 + QML**.
   - It runs **tray-only**: the tray icon opens the main flyout, with a separate settings window and hidden-items window.
   - The core job is to **enumerate Windows audio devices and sessions, filter/sort them, and let the user manage visibility and labels**.

2. **Application entry and bootstrapping**
   - `main.cpp` is the application entry point.
   - Startup likely wires together the Qt application, COM initialization, the central controller, QML engine, and the models exposed to QML.
   - `include/ComInit.h` / `src/ComInit.cpp` indicate COM is initialized as part of startup because the app depends on Windows Core Audio APIs.

3. **Top-level orchestration**
   - `AppController` is the central coordinator between UI, persistence, and audio state.
   - It is the main boundary between the **QML frontend** and the **audio/device backend**.
   - The controller likely handles actions such as toggling windows, applying hidden-device/process rules, changing mode, and refreshing state after audio events.

4. **UI layer: QML views**
   - The UI is implemented in `qml/`.
   - `Main.qml` is the primary tray flyout or mixer view.
   - `SettingsWindow.qml` contains application preferences such as device visibility and session display options.
   - `HiddenItemsWindow.qml` likely surfaces hidden devices/processes for management.
   - Reusable controls live in `qml/components/`, and theming/styling is in `qml/styles/`.

5. **View-model / data exposure layer**
   - `DeviceListModel`, `SessionListModel`, and `DeviceDirectionProxyModel` are the Qt model layer exposed to QML.
   - These models are the bridge from backend state to the visual lists in QML.
   - The proxy model suggests the UI can present devices by direction or category without duplicating backend state.
   - This is a key architectural boundary: **backend objects are normalized into Qt models before reaching QML**.

6. **Audio domain and Windows Core Audio integration**
   - `AudioBackend` is the main audio-system abstraction.
   - `AudioDevice` and `AudioSession` are domain objects wrapping Windows audio concepts like **IMMDevice** and per-process sessions.
   - `AudioWorker` implies audio enumeration and updates run off the UI thread to avoid blocking the interface.
   - The app’s core domain flow is:
     - enumerate devices/sessions,
     - build device/session objects,
     - filter by settings,
     - expose them through models.

7. **State updates and responsiveness**
   - `UpdateCoalescer` indicates the app batches rapid backend changes into fewer UI refreshes.
   - That matters in an audio mixer because Windows session/device changes can be noisy and frequent.
   - This component sits between low-level audio change notifications and the Qt models/UI, preventing excessive redraws or model churn.

8. **Configuration and persistence**
   - `ConfigStore` persists user settings to `%APPDATA%/Earie/config.json`.
   - The config is JSON-based and versioned (`schemaVersion: 2`).
   - Persisted state includes:
     - operating mode (`default` vs `all`),
     - whether to show system sessions,
     - whether to show input devices,
     - device display names and colors,
     - hidden devices,
     - hidden processes globally and per device.
   - The config layer is the source of truth for user preferences and filtering rules.

9. **Filtering and identity rules**
   - Devices are tracked by **stable IMMDevice IDs**.
   - Processes are hidden by **full executable path** resolved from session PID, which makes the hidden-process logic more stable than using only process names.
   - This is important for architecture because visibility is not just a UI concern; it is part of the persisted domain model and affects how sessions are included in the mixer.

10. **Windows-specific UI integration**
   - `WinAcrylic` and `WinTrayPositioner` are Windows UI helpers.
   - These likely adapt Qt windows to Windows 11-style acrylic effects and position the flyout relative to the system tray.
   - This is a small but distinct platform layer separate from the main audio logic and QML UI.

11. **Platform/support headers**
   - `include/win/ComPtr.h`, `Hr.h`, and `Utf.h` are utility wrappers for safer Windows API usage.
   - They reduce boilerplate around COM pointers, HRESULT handling, and UTF conversion.
   - `include/Audio*` and `include/Device*` headers define the main backend interfaces consumed by the rest of the app.

12. **Packaging and deployment**
   - `installer/` contains an **NSIS installer** and release scripts.
   - The README notes both an installer build and a portable ZIP build.
   - The installer adds system integration such as Start Menu entries and auto-update support, while the portable build intentionally avoids that integration.

13. **Assets and resources**
   - `resources.qrc` bundles runtime assets into the application.
   - `assets/` and `.github/assets/` contain branding and showcase images.
   - The packaged icon and QML styling support the app’s tray-centric visual identity.

14. **Overall data flow to draw in a diagram**
   - **Windows audio system** → `AudioBackend` / `AudioWorker` → `AudioDevice` / `AudioSession`
   - then into `DeviceListModel` / `SessionListModel` / proxy models
   - then into QML screens (`Main`, `Settings`, `HiddenItems`)
   - with `AppController` mediating actions and `ConfigStore` persisting changes
   - plus Windows-specific helpers for tray placement and window styling.

Main entry points: [`include/AppController.h`](https://github.com/tfourj/earie/blob/master/include/AppController.h) (AppController), [`qml/Main.qml`](https://github.com/tfourj/earie/blob/master/qml/Main.qml) (Main.qml), [`main.cpp`](https://github.com/tfourj/earie/blob/master/main.cpp) (main.cpp), [`include/AudioBackend.h`](https://github.com/tfourj/earie/blob/master/include/AudioBackend.h) (AudioBackend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_main_cpp(("main.cpp<br/>entrypoint<br/>[main.cpp]"))
  node_com_init["COM init<br/>startup helper<br/>[ComInit.h]"]
  node_app_controller["AppController<br/>orchestrator<br/>[AppController.h]"]
end

subgraph group_group_audio["Audio core"]
  node_audio_backend["AudioBackend<br/>audio facade<br/>[AudioBackend.h]"]
  node_audio_worker["AudioWorker<br/>[AudioWorker.h]"]
  node_audio_device["AudioDevice<br/>device domain<br/>[AudioDevice.h]"]
  node_audio_session["AudioSession<br/>session domain<br/>[AudioSession.h]"]
  node_update_coalescer["UpdateCoalescer<br/>event coalescer<br/>[UpdateCoalescer.h]"]
  node_device_list_model["DeviceListModel<br/>qt model<br/>[DeviceListModel.h]"]
  node_session_list_model["SessionListModel<br/>qt model<br/>[SessionListModel.h]"]
  node_device_direction_proxy["Direction proxy<br/>qt proxy model"]
end

subgraph group_group_ui["Qt UI"]
  node_main_qml["Main.qml<br/>flyout view<br/>[Main.qml]"]
  node_settings_qml["SettingsWindow.qml<br/>settings view<br/>[SettingsWindow.qml]"]
  node_hidden_qml["HiddenItemsWindow.qml<br/>management view"]
  node_device_cell["DeviceCell<br/>qml component<br/>[DeviceCell.qml]"]
  node_session_row["SessionRow<br/>qml component<br/>[SessionRow.qml]"]
end

subgraph group_group_platform["Platform"]
  node_win_acrylic["WinAcrylic<br/>windows ui helper<br/>[WinAcrylic.h]"]
  node_tray_positioner["Tray positioner<br/>windows ui helper"]
end

subgraph group_group_storage["Storage"]
  node_config_store["ConfigStore<br/>persistence<br/>[ConfigStore.h]"]
end

subgraph group_group_packaging["Packaging"]
  node_installer["Installer<br/>deployment<br/>[installer.nsi]"]
end

node_main_cpp -->|"initializes"| node_com_init
node_main_cpp -->|"creates"| node_app_controller
node_main_cpp -->|"boots"| node_audio_backend
node_main_cpp -->|"exposes"| node_device_list_model
node_main_cpp -->|"exposes"| node_session_list_model
node_app_controller -->|"loads/saves"| node_config_store
node_app_controller -->|"drives"| node_audio_backend
node_app_controller -->|"feeds"| node_device_list_model
node_app_controller -->|"feeds"| node_session_list_model
node_app_controller -->|"configures"| node_device_direction_proxy
node_audio_backend -->|"delegates"| node_audio_worker
node_audio_backend -->|"builds"| node_audio_device
node_audio_backend -->|"builds"| node_audio_session
node_audio_worker -->|"notifies"| node_update_coalescer
node_update_coalescer -->|"refreshes"| node_device_list_model
node_update_coalescer -->|"refreshes"| node_session_list_model
node_device_list_model -->|"renders in"| node_main_qml
node_session_list_model -->|"renders in"| node_main_qml
node_device_direction_proxy -->|"filters for"| node_main_qml
node_main_qml -->|"opens"| node_settings_qml
node_main_qml -->|"opens"| node_hidden_qml
node_main_qml -->|"uses"| node_device_cell
node_main_qml -->|"uses"| node_session_row
node_settings_qml -->|"edits"| node_config_store
node_hidden_qml -->|"edits"| node_config_store
node_app_controller -->|"applies"| node_win_acrylic
node_app_controller -->|"positions"| node_tray_positioner
node_installer -.->|"packages"| node_main_cpp

click node_main_cpp "https://github.com/tfourj/earie/blob/master/main.cpp"
click node_com_init "https://github.com/tfourj/earie/blob/master/include/ComInit.h"
click node_app_controller "https://github.com/tfourj/earie/blob/master/include/AppController.h"
click node_audio_backend "https://github.com/tfourj/earie/blob/master/include/AudioBackend.h"
click node_audio_worker "https://github.com/tfourj/earie/blob/master/include/AudioWorker.h"
click node_audio_device "https://github.com/tfourj/earie/blob/master/include/AudioDevice.h"
click node_audio_session "https://github.com/tfourj/earie/blob/master/include/AudioSession.h"
click node_update_coalescer "https://github.com/tfourj/earie/blob/master/include/UpdateCoalescer.h"
click node_device_list_model "https://github.com/tfourj/earie/blob/master/include/DeviceListModel.h"
click node_session_list_model "https://github.com/tfourj/earie/blob/master/include/SessionListModel.h"
click node_device_direction_proxy "https://github.com/tfourj/earie/blob/master/include/DeviceDirectionProxyModel.h"
click node_config_store "https://github.com/tfourj/earie/blob/master/include/ConfigStore.h"
click node_main_qml "https://github.com/tfourj/earie/blob/master/qml/Main.qml"
click node_settings_qml "https://github.com/tfourj/earie/blob/master/qml/SettingsWindow.qml"
click node_hidden_qml "https://github.com/tfourj/earie/blob/master/qml/HiddenItemsWindow.qml"
click node_device_cell "https://github.com/tfourj/earie/blob/master/qml/components/DeviceCell.qml"
click node_session_row "https://github.com/tfourj/earie/blob/master/qml/components/SessionRow.qml"
click node_win_acrylic "https://github.com/tfourj/earie/blob/master/include/WinAcrylic.h"
click node_tray_positioner "https://github.com/tfourj/earie/blob/master/include/WinTrayPositioner.h"
click node_installer "https://github.com/tfourj/earie/blob/master/installer/installer/installer.nsi"

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_cpp,node_com_init,node_app_controller toneBlue
class node_audio_backend,node_audio_worker,node_audio_device,node_audio_session,node_update_coalescer,node_device_list_model,node_session_list_model,node_device_direction_proxy toneAmber
class node_main_qml,node_settings_qml,node_hidden_qml,node_device_cell,node_session_row toneMint
class node_win_acrylic,node_tray_positioner toneRose
class node_config_store toneIndigo
class node_installer toneTeal
```

## Components

### Runtime

Application startup and cross-cutting coordination

- [main.cpp](https://github.com/tfourj/earie/blob/master/main.cpp): entrypoint · Qt application entry and startup wiring · `main.cpp`
- [COM init](https://github.com/tfourj/earie/blob/master/include/ComInit.h): startup helper · Initializes Windows COM for Core Audio use · `include/ComInit.h`
- [AppController](https://github.com/tfourj/earie/blob/master/include/AppController.h): orchestrator · Coordinates UI actions, persistence, and backend state · `include/AppController.h`

### Audio core

Windows audio enumeration, domain objects, and refresh flow

- [AudioBackend](https://github.com/tfourj/earie/blob/master/include/AudioBackend.h): audio facade · Main boundary to Windows audio enumeration and updates · `include/AudioBackend.h`
- [AudioWorker](https://github.com/tfourj/earie/blob/master/include/AudioWorker.h): worker · Runs audio enumeration and refresh work off the UI thread · `include/AudioWorker.h`
- [AudioDevice](https://github.com/tfourj/earie/blob/master/include/AudioDevice.h): device domain · Represents a Windows audio device and its metadata · `include/AudioDevice.h`
- [AudioSession](https://github.com/tfourj/earie/blob/master/include/AudioSession.h): session domain · Represents a per-process audio session · `include/AudioSession.h`
- [UpdateCoalescer](https://github.com/tfourj/earie/blob/master/include/UpdateCoalescer.h): event coalescer · Batches noisy backend changes into fewer UI updates · `include/UpdateCoalescer.h`
- [DeviceListModel](https://github.com/tfourj/earie/blob/master/include/DeviceListModel.h): qt model · Exposes devices to QML lists · `include/DeviceListModel.h`
- [SessionListModel](https://github.com/tfourj/earie/blob/master/include/SessionListModel.h): qt model · Exposes sessions to QML lists · `include/SessionListModel.h`
- [Direction proxy](https://github.com/tfourj/earie/blob/master/include/DeviceDirectionProxyModel.h): qt proxy model · Filters or groups devices by direction for the UI · `include/DeviceDirectionProxyModel.h`

### Qt UI

QML views and reusable presentation components

- [Main.qml](https://github.com/tfourj/earie/blob/master/qml/Main.qml): flyout view · Primary tray flyout mixer UI · `qml/Main.qml`
- [SettingsWindow.qml](https://github.com/tfourj/earie/blob/master/qml/SettingsWindow.qml): settings view · Application preferences and visibility controls · `qml/SettingsWindow.qml`
- [HiddenItemsWindow.qml](https://github.com/tfourj/earie/blob/master/qml/HiddenItemsWindow.qml): management view · Window for managing hidden devices and processes · `qml/HiddenItemsWindow.qml`
- [DeviceCell](https://github.com/tfourj/earie/blob/master/qml/components/DeviceCell.qml): qml component · Reusable device row element · `qml/components/DeviceCell.qml`
- [SessionRow](https://github.com/tfourj/earie/blob/master/qml/components/SessionRow.qml): qml component · Reusable session row element · `qml/components/SessionRow.qml`

### Platform

Windows-specific window and COM helpers

- [WinAcrylic](https://github.com/tfourj/earie/blob/master/include/WinAcrylic.h): windows ui helper · Applies Windows acrylic styling to Qt windows · `include/WinAcrylic.h`
- [Tray positioner](https://github.com/tfourj/earie/blob/master/include/WinTrayPositioner.h): windows ui helper · Positions the flyout relative to the system tray · `include/WinTrayPositioner.h`

### Storage

Configuration persistence and user state

- [ConfigStore](https://github.com/tfourj/earie/blob/master/include/ConfigStore.h): persistence · Persists settings, visibility rules, and labels as JSON · `include/ConfigStore.h`

### Packaging

Installer and deployment scripts

- [Installer](https://github.com/tfourj/earie/blob/master/installer/installer/installer.nsi): deployment · NSIS installer and release scripts · `installer/installer/installer.nsi`

## Connections

- main.cpp → COM init: initializes · Startup prepares COM before Core Audio access
- main.cpp → AppController: creates · Entry point constructs the central controller
- main.cpp → AudioBackend: boots · Startup wires backend state into the app
- main.cpp → DeviceListModel: exposes · Models are registered for QML consumption
- main.cpp → SessionListModel: exposes · Models are registered for QML consumption
- AppController → ConfigStore: loads/saves · Controller applies persisted preferences and updates config
- AppController → AudioBackend: drives · Controller requests refreshes and applies user actions
- AppController → DeviceListModel: feeds · Controller supplies device state to the UI model
- AppController → SessionListModel: feeds · Controller supplies session state to the UI model
- AppController → Direction proxy: configures · Controller sets up presentation-level device grouping
- AudioBackend → AudioWorker: delegates · Backend offloads enumeration and refresh work
- AudioBackend → AudioDevice: builds · Backend normalizes Windows devices into domain objects
- AudioBackend → AudioSession: builds · Backend normalizes Windows sessions into domain objects
- AudioWorker → UpdateCoalescer: notifies · Worker events are throttled before reaching models
- UpdateCoalescer → DeviceListModel: refreshes · Batched changes update the device list model
- UpdateCoalescer → SessionListModel: refreshes · Batched changes update the session list model
- DeviceListModel → Main.qml: renders in · Device data is displayed in the main mixer view
- SessionListModel → Main.qml: renders in · Session data is displayed in the main mixer view
- Direction proxy → Main.qml: filters for · Proxy shapes device presentation in the UI
- Main.qml → SettingsWindow.qml: opens · Main flyout links to settings
- Main.qml → HiddenItemsWindow.qml: opens · Main flyout links to hidden-items management
- Main.qml → DeviceCell: uses · Main view composes reusable device controls
- Main.qml → SessionRow: uses · Main view composes reusable session controls
- SettingsWindow.qml → ConfigStore: edits · Settings change persisted visibility and labeling rules
- HiddenItemsWindow.qml → ConfigStore: edits · Hidden-item management updates persisted rules
- AppController → WinAcrylic: applies · Controller coordinates platform-specific window styling
- AppController → Tray positioner: positions · Controller helps place tray flyouts correctly
- Installer → main.cpp: packages · Installer delivers the application build
