# osouthgate/omarchy-minimize architecture

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

- Interactive diagram: https://gitdiagram.com/osouthgate/omarchy-minimize
- Repository: https://github.com/osouthgate/omarchy-minimize

## Overview

Omarchy Minimize is an Omarchy bar widget and service for hiding individual Hyprland windows, listing minimized and compatible scratchpad/Dock windows, and restoring them by compositor address. Its main flow runs from bar or keyboard actions through the service, which reconciles live compositor clients, plans address-guarded moves, and updates the sidebar. Users can also review help and configure optional conflict-checked shortcuts. The README documents service behavior and session-scoped metadata; sampled source covers the pure model and transaction builders, but not their runtime wiring.

Main entry points: [`Service.qml`](https://github.com/osouthgate/omarchy-minimize/blob/main/Service.qml) (Minimize service), [`bin/configure-shortcuts`](https://github.com/osouthgate/omarchy-minimize/blob/main/bin/configure-shortcuts) (Shortcut configurator), [`ShortcutSettingsView.qml`](https://github.com/osouthgate/omarchy-minimize/blob/main/ShortcutSettingsView.qml) (Shortcut settings), [`Panel.qml`](https://github.com/osouthgate/omarchy-minimize/blob/main/Panel.qml) (Bar widget)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Sidebar interface"]
  node_bar["Bar widget<br/>[Panel.qml]"]
  node_window_row["Window row<br/>[WindowRow.qml]"]
  node_help["Help view<br/>[HelpView.qml]"]
  node_shortcut_view["Shortcut settings"]
end

subgraph group_runtime["Window management"]
  node_service["Minimize service<br/>[Service.qml]"]
  node_model["Client model<br/>[MinimizeModel.js]"]
  node_transaction["Compositor transactions"]
  node_metadata[("Session metadata<br/>[Service.qml]")]
end

subgraph group_shortcuts["Shortcut setup"]
  node_shortcut_tool["Shortcut configurator"]
end

subgraph group_integrations["Desktop integration"]
  node_omarchy["Omarchy shell"]
  node_hyprland["Hyprland compositor"]
  node_binding_file["Hyprland bindings"]
end

node_user(("User"))

node_user -->|"clicks"| node_bar
node_user -->|"selects"| node_window_row
node_user -->|"configures"| node_shortcut_view
node_bar -->|"invokes actions"| node_service
node_window_row -->|"requests restore"| node_service
node_shortcut_view -->|"requests actions"| node_service
node_service -->|"plans and reconciles"| node_model
node_service -->|"builds moves"| node_transaction
node_service -->|"queries clients and dispatches"| node_hyprland
node_hyprland -->|"returns live state"| node_service
node_service -->|"reads and writes"| node_metadata
node_omarchy -->|"dispatches commands"| node_service
node_shortcut_view -.->|"optional setup"| node_shortcut_tool
node_shortcut_tool -->|"checks binds and reloads"| node_hyprland
node_shortcut_tool -->|"backs up and edits"| node_binding_file
node_shortcut_tool -->|"validates config"| node_hyprland

click node_bar "https://github.com/osouthgate/omarchy-minimize/blob/main/Panel.qml"
click node_window_row "https://github.com/osouthgate/omarchy-minimize/blob/main/WindowRow.qml"
click node_help "https://github.com/osouthgate/omarchy-minimize/blob/main/HelpView.qml"
click node_shortcut_view "https://github.com/osouthgate/omarchy-minimize/blob/main/ShortcutSettingsView.qml"
click node_service "https://github.com/osouthgate/omarchy-minimize/blob/main/Service.qml"
click node_model "https://github.com/osouthgate/omarchy-minimize/blob/main/MinimizeModel.js"
click node_transaction "https://github.com/osouthgate/omarchy-minimize/blob/main/CompositorTransaction.js"
click node_metadata "https://github.com/osouthgate/omarchy-minimize/blob/main/Service.qml"
click node_shortcut_tool "https://github.com/osouthgate/omarchy-minimize/blob/main/bin/configure-shortcuts"

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_bar,node_window_row,node_help,node_shortcut_view,node_user toneBlue
class node_service,node_model,node_transaction,node_metadata toneAmber
class node_shortcut_tool toneMint
class node_omarchy,node_hyprland,node_binding_file toneRose
```

## Components

### Sidebar interface

- [Bar widget](https://github.com/osouthgate/omarchy-minimize/blob/main/Panel.qml): `Panel.qml`
- [Window row](https://github.com/osouthgate/omarchy-minimize/blob/main/WindowRow.qml): `WindowRow.qml`
- [Help view](https://github.com/osouthgate/omarchy-minimize/blob/main/HelpView.qml): `HelpView.qml`
- [Shortcut settings](https://github.com/osouthgate/omarchy-minimize/blob/main/ShortcutSettingsView.qml): `ShortcutSettingsView.qml`

### Window management

- [Minimize service](https://github.com/osouthgate/omarchy-minimize/blob/main/Service.qml): `Service.qml`
- [Client model](https://github.com/osouthgate/omarchy-minimize/blob/main/MinimizeModel.js): `MinimizeModel.js`
- [Compositor transactions](https://github.com/osouthgate/omarchy-minimize/blob/main/CompositorTransaction.js): `CompositorTransaction.js`
- [Session metadata](https://github.com/osouthgate/omarchy-minimize/blob/main/Service.qml): `Service.qml`

### Shortcut setup

- [Shortcut configurator](https://github.com/osouthgate/omarchy-minimize/blob/main/bin/configure-shortcuts): `bin/configure-shortcuts`

### Desktop integration

- **Omarchy shell**
- **Hyprland compositor**
- **Hyprland bindings**

### Other components

- **User**

## Connections

- User → Bar widget: clicks
- User → Window row: selects
- User → Shortcut settings: configures
- Bar widget → Minimize service: invokes actions
- Window row → Minimize service: requests restore
- Shortcut settings → Minimize service: requests actions
- Minimize service → Client model: plans and reconciles
- Minimize service → Compositor transactions: builds moves
- Minimize service → Hyprland compositor: queries clients and dispatches
- Hyprland compositor → Minimize service: returns live state
- Minimize service → Session metadata: reads and writes
- Omarchy shell → Minimize service: dispatches commands
- Shortcut settings → Shortcut configurator: optional setup
- Shortcut configurator → Hyprland compositor: checks binds and reloads
- Shortcut configurator → Hyprland bindings: backs up and edits
- Shortcut configurator → Hyprland compositor: validates config