How ilyamiro/nixos-configuration works
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: templates Theme templates · quickshell Shell panels · scripts Session scripts · default.nix Session Nix
Components 20
Nix layer
Packaging and composition boundary for the desktop configuration.
- Root Nix · Top-level system and home composition for the environment.
configuration.nix - Home config · User-level Nix wiring that pulls in programs and session pieces.
home.nix - Session Nix · Hyprland session packaging and activation boundary.
config/sessions/hyprland/default.nix - Program Nix · Program-specific Nix modules for installed desktop endpoints.
config/programs
Hyprland session
Compositor session entrypoint, orchestration, and runtime glue.
- Hyprland config · Assembled compositor configuration consumed at session start.
config/sessions/hyprland/hyprland.conf - Session fragments · Environment, monitors, keybindings, rules, settings, variables, and autostart fragments.
config/sessions/hyprland/config - Session 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 · Main Quickshell entry and shared shell scaffolding.
config/sessions/hyprland/scripts/quickshell/Main.qml - Shell surface · Top bar, lock screen, floating state, scaling, screenshot overlay, and window registry.
config/sessions/hyprland/scripts/quickshell - Shell panels · 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 · Continuous collectors that sample audio, battery, Bluetooth, keyboard, network, and system usage state.
config/sessions/hyprland/scripts/quickshell/watchers - Control helpers · 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 · Wallpaper-derived palette generation and theme file emission.
config/programs/matugen - Theme templates · 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 · Terminal emulator configuration and color consumer.
config/programs/kitty - Neovim · Editor runtime and theming endpoint.
config/programs/neovim - Rofi · Application launcher theming and behavior endpoint.
config/programs/rofi - Zsh · Interactive shell initialization and session shell behavior.
config/programs/zsh - SwayOSD · On-screen display styling for desktop feedback.
config/programs/swayosd - Plymouth · Boot-time splash configuration and resources.
config/programs/plymouth
Connections 22
- 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.