# ilyamiro/nixos-configuration architecture

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

- Interactive diagram: https://gitdiagram.com/ilyamiro/nixos-configuration
- Repository: https://github.com/ilyamiro/nixos-configuration

## Overview

1. This repository is a desktop-environment configuration repo, centered on a Hyprland Wayland session plus a Quickshell-based custom shell. Its job is to assemble the compositor session, launch the UI layers, keep system state visible, and keep visual theming consistent across apps.

2. The repo has two configuration strata: Nix files at the root and under `config/**/default.nix`, and the actual runtime configs/scripts/QML files they install. The Nix layer is the packaging and composition boundary; the runtime layer is where Hyprland, Quickshell, and user-facing tools actually run.

3. `config/sessions/hyprland/` is the session entrypoint. It contains Hyprland config fragments for environment, monitors, keybindings, rules, settings, and autostart, plus helper scripts such as reload, lock, exit, screenshot, workspace management, and volume listening. This is the orchestration layer that starts the desktop and wires the rest of the system together.

4. `config/sessions/hyprland/scripts/quickshell/` is the main UI subsystem. The top-level QML files (`Main.qml`, `Shell.qml`, `TopBar.qml`, `Lock.qml`, etc.) define the shell surface, while feature folders implement popups and panels for battery, calendar, clipboard, focus time, music, network, notifications, quick actions, updater, volume, wallpaper, and monitors.

5. Quickshell widgets are fed by local helper scripts and small Python utilities. Each subsystem has its own fetch/control pair in many cases: audio, battery, Bluetooth, keyboard, network, and system usage are polled by watcher scripts; actions like toggling volume, controlling music, or launching the focus daemon are delegated to shell/Python helpers. The UI is therefore mostly declarative QML over a local state pipeline.

6. The `watchers/` folder is the data-collection backbone for the shell. These scripts continuously sample system state and push it into the UI layer, which keeps the shell responsive without embedding all polling logic in QML. This is a clear separation between presentation and state acquisition.

7. The theming pipeline is centralized in `config/programs/matugen/`. Matugen consumes wallpaper-derived colors and emits themed assets from templates for Kitty, GTK, Neovim, Hyprland, Qt, CAVA, Discord, Firefox, swayosd, and website styles. In practice, wallpaper changes feed into color generation, then generated theme files are reloaded into the active desktop.

8. The repo also configures individual user programs under `config/programs/`: Kitty, Neovim, Rofi, Zsh, CAVA, swayosd, and Plymouth. These are not separate applications in the architecture so much as endpoints that consume the shared theme and session settings, keeping the shell coherent across terminal, editor, launcher, login splash, and notifications.

9. Some subsystems integrate external or semi-external data sources. The wallpaper picker uses DuckDuckGo search helpers; the calendar and weather components pull schedule/weather data; the music and network panels expose local device state; and there are website theme templates for GitHub and YouTube. The architecture is mostly local-first, but with a few fetchers that depend on online content.

10. Deployment-wise, the repo is opinionated: the README says the current release is not meant for NixOS in its present form and is installed via an Arch-oriented installer, even though the repo contains Nix expressions. For diagramming, treat the Nix files as the build/install layer, Hyprland as the compositor runtime, Quickshell as the interactive shell runtime, and the helper scripts/watchers as the state and control plane connecting them.

Main entry points: [`config/programs/matugen/templates`](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/matugen/templates) (Theme templates), [`config/sessions/hyprland/scripts/quickshell`](https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell) (Shell panels), [`config/sessions/hyprland/scripts`](https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts) (Session scripts), [`config/sessions/hyprland/default.nix`](https://github.com/ilyamiro/nixos-configuration/blob/master/config/sessions/hyprland/default.nix) (Session Nix)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_nix["Nix layer"]
  node_nix_root["Root Nix<br/>nix entry<br/>[configuration.nix]"]
  node_home_nix["Home config<br/>nix home<br/>[home.nix]"]
  node_session_nix["Session Nix<br/>nix session<br/>[default.nix]"]
  node_programs_nix["Program Nix<br/>nix programs"]
end

subgraph group_grp_session["Hyprland session"]
  node_hyprland_cfg["Hyprland config<br/>compositor config<br/>[hyprland.conf]"]
  node_session_parts["Session fragments<br/>hyprland fragments"]
  node_session_scripts["Session scripts<br/>control scripts"]
end

subgraph group_grp_shell["Quickshell UI"]
  node_quickshell_main["Shell core<br/>qml shell<br/>[Main.qml]"]
  node_quickshell_surface["Shell surface<br/>qml layout"]
  node_quickshell_panels["Shell panels<br/>qml widgets"]
  node_watchers["Watchers<br/>state polling"]
  node_control_helpers["Control helpers<br/>shell/python glue"]
end

subgraph group_grp_theme["Theming pipeline"]
  node_matugen["Matugen<br/>theme generator"]
  node_theme_templates["Theme templates<br/>template set"]
end

subgraph group_grp_programs["User programs"]
  node_kitty["Kitty<br/>terminal config"]
  node_neovim["Neovim<br/>editor config"]
  node_rofi["Rofi<br/>launcher config"]
  node_zsh["Zsh<br/>shell config"]
  node_swayosd["SwayOSD<br/>osd config"]
  node_plymouth["Plymouth<br/>boot splash"]
end

node_nix_root -->|"includes"| node_home_nix
node_nix_root -->|"installs"| node_session_nix
node_home_nix -->|"enables"| node_programs_nix
node_session_nix -->|"renders"| node_hyprland_cfg
node_hyprland_cfg -->|"imports"| node_session_parts
node_session_parts -->|"launches"| node_session_scripts
node_session_nix -->|"starts"| node_quickshell_main
node_quickshell_main -->|"composes"| node_quickshell_surface
node_quickshell_main -->|"hosts"| node_quickshell_panels
node_quickshell_panels -->|"subscribes"| node_watchers
node_quickshell_panels -->|"invokes"| node_control_helpers
node_watchers -->|"feeds"| node_control_helpers
node_session_scripts -->|"starts"| node_watchers
node_session_scripts -->|"calls"| node_control_helpers
node_quickshell_panels -->|"reloads theme"| node_matugen
node_matugen -->|"emits"| node_theme_templates
node_theme_templates -->|"styles"| node_kitty
node_theme_templates -->|"styles"| node_neovim
node_theme_templates -->|"styles"| node_rofi
node_theme_templates -->|"styles"| node_swayosd
node_theme_templates -->|"styles"| node_plymouth
node_quickshell_panels -->|"controls session"| node_session_scripts

click node_nix_root "https://github.com/ilyamiro/nixos-configuration/blob/master/configuration.nix"
click node_home_nix "https://github.com/ilyamiro/nixos-configuration/blob/master/home.nix"
click node_session_nix "https://github.com/ilyamiro/nixos-configuration/blob/master/config/sessions/hyprland/default.nix"
click node_programs_nix "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs"
click node_hyprland_cfg "https://github.com/ilyamiro/nixos-configuration/blob/master/config/sessions/hyprland/hyprland.conf"
click node_session_parts "https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/config"
click node_session_scripts "https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts"
click node_quickshell_main "https://github.com/ilyamiro/nixos-configuration/blob/master/config/sessions/hyprland/scripts/quickshell/Main.qml"
click node_quickshell_surface "https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell"
click node_quickshell_panels "https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell"
click node_watchers "https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell/watchers"
click node_control_helpers "https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell"
click node_matugen "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/matugen"
click node_theme_templates "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/matugen/templates"
click node_kitty "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/kitty"
click node_neovim "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/neovim"
click node_rofi "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/rofi"
click node_zsh "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/zsh"
click node_swayosd "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/swayosd"
click node_plymouth "https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/plymouth"

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_nix_root,node_home_nix,node_session_nix,node_programs_nix toneBlue
class node_hyprland_cfg,node_session_parts,node_session_scripts toneAmber
class node_quickshell_main,node_quickshell_surface,node_quickshell_panels,node_watchers,node_control_helpers toneMint
class node_matugen,node_theme_templates toneRose
class node_kitty,node_neovim,node_rofi,node_zsh,node_swayosd,node_plymouth toneIndigo
```

## Components

### Nix layer

Packaging and composition boundary for the desktop configuration.

- [Root Nix](https://github.com/ilyamiro/nixos-configuration/blob/master/configuration.nix): nix entry · Top-level system and home composition for the environment. · `configuration.nix`
- [Home config](https://github.com/ilyamiro/nixos-configuration/blob/master/home.nix): nix home · User-level Nix wiring that pulls in programs and session pieces. · `home.nix`
- [Session Nix](https://github.com/ilyamiro/nixos-configuration/blob/master/config/sessions/hyprland/default.nix): nix session · Hyprland session packaging and activation boundary. · `config/sessions/hyprland/default.nix`
- [Program Nix](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs): nix programs · Program-specific Nix modules for installed desktop endpoints. · `config/programs`

### Hyprland session

Compositor session entrypoint, orchestration, and runtime glue.

- [Hyprland config](https://github.com/ilyamiro/nixos-configuration/blob/master/config/sessions/hyprland/hyprland.conf): compositor config · Assembled compositor configuration consumed at session start. · `config/sessions/hyprland/hyprland.conf`
- [Session fragments](https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/config): hyprland fragments · Environment, monitors, keybindings, rules, settings, variables, and autostart fragments. · `config/sessions/hyprland/config`
- [Session scripts](https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts): control scripts · Reload, lock, exit, screenshot, workspace, caching, and volume listener helpers. · `config/sessions/hyprland/scripts`

### Quickshell UI

Declarative shell surface and panel widgets.

- [Shell core](https://github.com/ilyamiro/nixos-configuration/blob/master/config/sessions/hyprland/scripts/quickshell/Main.qml): qml shell · Main Quickshell entry and shared shell scaffolding. · `config/sessions/hyprland/scripts/quickshell/Main.qml`
- [Shell surface](https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell): qml layout · Top bar, lock screen, floating state, scaling, screenshot overlay, and window registry. · `config/sessions/hyprland/scripts/quickshell`
- [Shell panels](https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell): qml widgets · User-facing popups and widgets for battery, calendar, clipboard, focus, music, network, notifications, quick actions, settings, updater, volume, wallpaper, and monitors. · `config/sessions/hyprland/scripts/quickshell`
- [Watchers](https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell/watchers): state polling · Continuous collectors that sample audio, battery, Bluetooth, keyboard, network, and system usage state. · `config/sessions/hyprland/scripts/quickshell/watchers`
- [Control helpers](https://github.com/ilyamiro/nixos-configuration/tree/master/config/sessions/hyprland/scripts/quickshell): shell/python glue · Local scripts and utilities that fetch data or execute shell actions for the UI. · `config/sessions/hyprland/scripts/quickshell`

### Theming pipeline

Wallpaper-driven color generation and downstream template outputs.

- [Matugen](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/matugen): theme generator · Wallpaper-derived palette generation and theme file emission. · `config/programs/matugen`
- [Theme templates](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/matugen/templates): template set · Generated targets for Kitty, GTK, Neovim, Hyprland, Qt, CAVA, Discord, Firefox, swayosd, and websites. · `config/programs/matugen/templates`

### User programs

Configured endpoints that consume session state and shared theming.

- [Kitty](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/kitty): terminal config · Terminal emulator configuration and color consumer. · `config/programs/kitty`
- [Neovim](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/neovim): editor config · Editor runtime and theming endpoint. · `config/programs/neovim`
- [Rofi](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/rofi): launcher config · Application launcher theming and behavior endpoint. · `config/programs/rofi`
- [Zsh](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/zsh): shell config · Interactive shell initialization and session shell behavior. · `config/programs/zsh`
- [SwayOSD](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/swayosd): osd config · On-screen display styling for desktop feedback. · `config/programs/swayosd`
- [Plymouth](https://github.com/ilyamiro/nixos-configuration/tree/master/config/programs/plymouth): boot splash · Boot-time splash configuration and resources. · `config/programs/plymouth`

## Connections

- Root Nix → Home config: includes · System composition pulls in user-level configuration.
- Root Nix → Session Nix: installs · Root Nix wires the desktop session package set.
- Home config → Program Nix: enables · Home configuration activates user programs.
- Session Nix → Hyprland config: renders · Session Nix assembles the compositor config.
- Hyprland config → Session fragments: imports · Main Hyprland config is built from fragments.
- Session fragments → Session scripts: launches · Autostart and bindings call into helper scripts.
- Session Nix → Shell core: starts · Session setup launches the Quickshell runtime.
- Shell core → Shell surface: composes · Core shell builds the visible shell surface.
- Shell core → Shell panels: hosts · Core shell hosts popup and panel widgets.
- Shell panels → Watchers: subscribes · Widgets consume continuously sampled state.
- Shell panels → Control helpers: invokes · Panels delegate actions and fetches to local helpers.
- Watchers → Control helpers: feeds · Polling layer and helpers together provide state to the UI.
- Session scripts → Watchers: starts · Session scripts launch or supervise watcher processes.
- Session scripts → Control helpers: calls · Desktop actions and utilities are executed through helpers.
- Shell panels → Matugen: reloads theme · Wallpaper and theme panels trigger palette regeneration.
- Matugen → Theme templates: emits · Color pipeline produces themed outputs from templates.
- Theme templates → Kitty: styles · Generated theme files feed the terminal config.
- Theme templates → Neovim: styles · Generated theme files feed the editor config.
- Theme templates → Rofi: styles · Generated theme files feed the launcher config.
- Theme templates → SwayOSD: styles · Generated theme files feed the OSD config.
- Theme templates → Plymouth: styles · Generated theme files and assets support the splash theme.
- Shell panels → Session scripts: controls session · UI actions like lock, exit, screenshot, and workspace control delegate to session scripts.
