# quantumfate/hypr architecture

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

- Interactive diagram: https://gitdiagram.com/quantumfate/hypr
- Repository: https://github.com/quantumfate/hypr

## Overview

Hypr is a multi-machine Hyprland desktop configuration: users operate a configured compositor through key bindings and window/workspace behavior, while scene documents describe window placement for scene engines to execute. Its runtime also includes focus/workspace management, layouts, themes, and optional desktop services such as Dofus turn swapping and Obsidian integrations. The README and tree establish these product areas, but the sampled source excerpts are mostly auxiliary Python tools; internal Lua call wiring is therefore shown only where supported by explicit documentation, and otherwise left unspecified.

Main entry points: [`hypr/scene`](https://github.com/quantumfate/hypr/tree/main/hypr/scene) (Scene engines), [`bin/obsidian_vault.py`](https://github.com/quantumfate/hypr/blob/main/bin/obsidian_vault.py) (Vault utilities), [`bin/obsidian_linear_sync.py`](https://github.com/quantumfate/hypr/blob/main/bin/obsidian_linear_sync.py) (Linear sync), [`bin/,scene-apply.sh`](https://github.com/quantumfate/hypr/blob/main/bin/%2Cscene-apply.sh) (Scene apply)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Desktop configuration"]
  node_entry["Compositor config<br/>[hyprland.lua]"]
  node_base["Base options<br/>[base.lua]"]
  node_host["Host options<br/>[host.lua]"]
  node_binds["Key bindings<br/>[binds.lua]"]
  node_workspaces["Workspace config<br/>[workspaces.lua]"]
  node_events["Compositor events<br/>[init.lua]"]
end

subgraph group_scenes["Scene management"]
  node_scene_docs["Scene documents<br/>[scenes.md]"]
  node_scene_apply["Scene apply<br/>[,scene-apply.sh]"]
  node_scene_engine["Scene engines"]
  node_grouping["Window grouping<br/>[grouping.lua]"]
  node_scene_layout["Scene layout<br/>[layout.lua]"]
end

subgraph group_focus["Focus and navigation"]
  node_focus_system["Hyprfocus"]
  node_focus_dispatch["Focus dispatcher"]
  node_layouts["Window layouts"]
end

subgraph group_integrations["Desktop integrations"]
  node_themes["Theme system"]
  node_dofus["Dofus services"]
  node_swap["Turn swap detector<br/>[dofus_swap.py]"]
  node_obsidian["Obsidian tooling"]
  node_vault["Vault utilities<br/>[obsidian_vault.py]"]
  node_linear["Linear sync"]
end

node_user(("Desktop user"))
node_compositor["Hyprland"]
node_obsidian_app["Obsidian"]
node_linear_service["Linear"]
node_vault_store[("Vault and tag store")]

node_user -->|"operates"| node_compositor
node_entry -->|"configures"| node_compositor
node_user -->|"uses"| node_binds
node_scene_docs -->|"describes placement"| node_scene_apply
node_scene_apply -->|"executes scenes"| node_scene_engine
node_scene_engine -->|"uses grouping"| node_grouping
node_scene_engine -->|"uses layout"| node_scene_layout
node_user -->|"invokes"| node_focus_dispatch
node_focus_dispatch -->|"dispatches"| node_focus_system
node_user -.->|"runs"| node_swap
node_swap -.->|"queries and focuses"| node_compositor
node_user -.->|"runs"| node_vault
node_vault -.->|"invokes CLI"| node_obsidian_app
node_vault -.->|"reads and writes"| node_vault_store
node_user -.->|"runs sync"| node_linear
node_linear -.->|"reads hierarchy"| node_linear_service
node_linear -.->|"updates notes"| node_vault_store

click node_entry "https://github.com/quantumfate/hypr/blob/main/hyprland.lua"
click node_base "https://github.com/quantumfate/hypr/blob/main/conf/base.lua"
click node_host "https://github.com/quantumfate/hypr/blob/main/conf/host.lua"
click node_binds "https://github.com/quantumfate/hypr/blob/main/hypr/binds.lua"
click node_workspaces "https://github.com/quantumfate/hypr/blob/main/hypr/workspaces.lua"
click node_events "https://github.com/quantumfate/hypr/blob/main/hypr/events/init.lua"
click node_scene_docs "https://github.com/quantumfate/hypr/blob/main/docs/scenes.md"
click node_scene_apply "https://github.com/quantumfate/hypr/blob/main/bin/%2Cscene-apply.sh"
click node_scene_engine "https://github.com/quantumfate/hypr/tree/main/hypr/scene"
click node_grouping "https://github.com/quantumfate/hypr/blob/main/hypr/scene/grouping.lua"
click node_scene_layout "https://github.com/quantumfate/hypr/blob/main/hypr/scene/layout.lua"
click node_focus_system "https://github.com/quantumfate/hypr/tree/main/hypr/hyprfocus"
click node_focus_dispatch "https://github.com/quantumfate/hypr/blob/main/bin/%2Chyprfocus"
click node_layouts "https://github.com/quantumfate/hypr/tree/main/hypr/layouts"
click node_themes "https://github.com/quantumfate/hypr/tree/main/hypr/themes"
click node_dofus "https://github.com/quantumfate/hypr/tree/main/hypr/services/dofus"
click node_swap "https://github.com/quantumfate/hypr/blob/main/bin/dofus_swap.py"
click node_obsidian "https://github.com/quantumfate/hypr/tree/main/hypr/services/obsidian"
click node_vault "https://github.com/quantumfate/hypr/blob/main/bin/obsidian_vault.py"
click node_linear "https://github.com/quantumfate/hypr/blob/main/bin/obsidian_linear_sync.py"

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_entry,node_base,node_host,node_binds,node_workspaces,node_events,node_user toneBlue
class node_scene_docs,node_scene_apply,node_scene_engine,node_grouping,node_scene_layout,node_vault_store toneAmber
class node_focus_system,node_focus_dispatch,node_layouts toneMint
class node_themes,node_dofus,node_swap,node_obsidian,node_vault,node_linear toneRose
class node_compositor,node_obsidian_app,node_linear_service toneIndigo
```

## Components

### Desktop configuration

- [Compositor config](https://github.com/quantumfate/hypr/blob/main/hyprland.lua): `hyprland.lua`
- [Base options](https://github.com/quantumfate/hypr/blob/main/conf/base.lua): `conf/base.lua`
- [Host options](https://github.com/quantumfate/hypr/blob/main/conf/host.lua): `conf/host.lua`
- [Key bindings](https://github.com/quantumfate/hypr/blob/main/hypr/binds.lua): `hypr/binds.lua`
- [Workspace config](https://github.com/quantumfate/hypr/blob/main/hypr/workspaces.lua): `hypr/workspaces.lua`
- [Compositor events](https://github.com/quantumfate/hypr/blob/main/hypr/events/init.lua): `hypr/events/init.lua`

### Scene management

- [Scene documents](https://github.com/quantumfate/hypr/blob/main/docs/scenes.md): `docs/scenes.md`
- [Scene apply](https://github.com/quantumfate/hypr/blob/main/bin/%2Cscene-apply.sh): `bin/,scene-apply.sh`
- [Scene engines](https://github.com/quantumfate/hypr/tree/main/hypr/scene): `hypr/scene`
- [Window grouping](https://github.com/quantumfate/hypr/blob/main/hypr/scene/grouping.lua): `hypr/scene/grouping.lua`
- [Scene layout](https://github.com/quantumfate/hypr/blob/main/hypr/scene/layout.lua): `hypr/scene/layout.lua`

### Focus and navigation

- [Hyprfocus](https://github.com/quantumfate/hypr/tree/main/hypr/hyprfocus): `hypr/hyprfocus`
- [Focus dispatcher](https://github.com/quantumfate/hypr/blob/main/bin/%2Chyprfocus): `bin/,hyprfocus`
- [Window layouts](https://github.com/quantumfate/hypr/tree/main/hypr/layouts): `hypr/layouts`

### Desktop integrations

- [Theme system](https://github.com/quantumfate/hypr/tree/main/hypr/themes): `hypr/themes`
- [Dofus services](https://github.com/quantumfate/hypr/tree/main/hypr/services/dofus): `hypr/services/dofus`
- [Turn swap detector](https://github.com/quantumfate/hypr/blob/main/bin/dofus_swap.py): `bin/dofus_swap.py`
- [Obsidian tooling](https://github.com/quantumfate/hypr/tree/main/hypr/services/obsidian): `hypr/services/obsidian`
- [Vault utilities](https://github.com/quantumfate/hypr/blob/main/bin/obsidian_vault.py): `bin/obsidian_vault.py`
- [Linear sync](https://github.com/quantumfate/hypr/blob/main/bin/obsidian_linear_sync.py): `bin/obsidian_linear_sync.py`

### Other components

- **Desktop user**
- **Hyprland**
- **Obsidian**
- **Linear**
- **Vault and tag store**

## Connections

- Desktop user → Hyprland: operates
- Compositor config → Hyprland: configures
- Desktop user → Key bindings: uses
- Scene documents → Scene apply: describes placement
- Scene apply → Scene engines: executes scenes
- Scene engines → Window grouping: uses grouping
- Scene engines → Scene layout: uses layout
- Desktop user → Focus dispatcher: invokes
- Focus dispatcher → Hyprfocus: dispatches
- Desktop user → Turn swap detector: runs
- Turn swap detector → Hyprland: queries and focuses
- Desktop user → Vault utilities: runs
- Vault utilities → Obsidian: invokes CLI
- Vault utilities → Vault and tag store: reads and writes
- Desktop user → Linear sync: runs sync
- Linear sync → Linear: reads hierarchy
- Linear sync → Vault and tag store: updates notes