# nischaldawadi/hyprlust architecture

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

- Interactive diagram: https://gitdiagram.com/nischaldawadi/hyprlust
- Repository: https://github.com/nischaldawadi/hyprlust

## Overview

1. This repository is a desktop-environment dotfiles bundle, not an application codebase. The architecture centers on a Wayland session driven by Hyprland, with many sub-configurations and helper scripts composing the user experience.

2. The core runtime layer is Hyprland itself: `hyprland.conf` plus files under `hypr/UserConfigs`, `hypr/configs`, `hypr/hypridle.conf`, `hypr/hyprlock.conf`, and `hypr/pyprland.toml`. These define monitor layout, keybinds, window rules, startup apps, idle/lock behavior, and workspace behavior.

3. User interaction is mostly mediated through scripts in `.config/hypr/scripts` and `.config/hypr/UserScripts`. These scripts are the control plane for common desktop actions: brightness, volume, screenshots, lock screen, clipboard, wallpaper changes, keyboard layout switching, gaming mode, media controls, and utility launchers. Hyprland keybinds invoke these scripts directly.

4. The visual theming pipeline is a major subsystem. Wallpaper/state-driven colors are generated by `wallust` and `matugen`, then propagated into app themes via templates for Hyprland, Kitty, Rofi, Waybar, SwayNC, Zathura, Qt (`qt5ct`, `qt6ct`, `Kvantum`), GTK 2/3/4, Starship, and other tool-specific configs. The repo’s look-and-feel is therefore data-driven from the wallpaper/palette layer downward.

5. The launcher and menu layer is Rofi-based. Multiple Rofi configs exist for search, clipboard, emoji, wallpaper selection/effects, Zsh theme switching, Waybar style/layout selection, and beats/music menus. These are not isolated utilities; they are the UI entry points for many Hyprland scripts.

6. Waybar is the status and command surface for the desktop. The repo contains many Waybar layouts and styles, plus wallust-generated colors. This implies a modular bar architecture where layout, widget set, and theme are selected independently per monitor/profile.

7. Notifications and session chrome are handled by SwayNC and Wlogout. SwayNC has its own style sheets and wallust-generated colors; Wlogout provides the session/logout menu. These integrate with Hyprland as session-level UI components rather than standalone apps.

8. Media is a distinct subsystem. MPD provides the music backend (`mpd.conf`, playlists, database/logs), while `mpDris2` exposes it to desktop controls. `rmpc` is the terminal client, and helper scripts in Hyprland and Rofi wrap playback controls. Video playback is handled through `mpv` with a heavy Lua script stack (`uosc`, sponsorblock, playlist manager, quality menu, thumbnails, etc.), showing a layered media-player customization.

9. Browser/app-specific customization is present for Spotify via Spicetify. The repo stores the extracted Spotify UI, custom apps, themes, and backup artifacts, which means Spotify is treated as a themable runtime with its own patching and extension layer. Similarly, Seanime, Upscayl, streamrip, and other apps keep their caches, logs, databases, and settings under `.config`, but those are runtime state, not source architecture.

10. Developer/editor tooling is also configured as part of the desktop stack. Neovim uses a LazyVim-style Lua config with plugin definitions, while Zsh and Starship define shell behavior and prompt theming. These sit alongside terminal apps like Kitty, Yazi, btop, fastfetch, and zathura to form the primary productivity environment.

11. There is a clear separation between source-like configuration and mutable state. The repo includes many persistent databases, caches, logs, and session files under app directories such as Seanime, MPD, Upscayl, Spotify/Spicetify, and yt-x. For architecture diagrams, these should be shown as local state stores attached to their respective apps, not as shared backend services.

12. Overall flow: wallpaper/theme selection feeds color generation, generated palettes propagate to desktop/app themes, Hyprland keybinds and scripts orchestrate behavior, and specialized apps (media, launcher, notifications, editor, music, browser tweaks) consume those configs. The repository’s main boundary is the user session itself: a themed, script-driven Linux desktop assembled from many independently configured clients.

Main entry points: [`.config/hypr/hyprland.conf`](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/hyprland.conf) (Hyprland), [`.config/wallust/templates`](https://github.com/nischaldawadi/hyprlust/blob/master/.config/wallust/templates) (Theme templates), [`.config/hypr/scripts`](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/scripts) (Control scripts), [`.config/mpd/mpd.conf`](https://github.com/nischaldawadi/hyprlust/blob/master/.config/mpd/mpd.conf) (MPD)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_session["Session"]
  node_hyprland["Hyprland<br/>session compositor<br/>[hyprland.conf]"]
  node_hypr_user_configs["User configs<br/>session config<br/>[UserConfigs]"]
  node_hypr_configs["Core configs<br/>session config<br/>[configs]"]
  node_pyprland["Pyprland<br/>session plugins<br/>[pyprland.toml]"]
end

subgraph group_theme["Theming"]
  node_wallpaper_state["Wallpaper state<br/>palette source<br/>[wallpaper_effects]"]
  node_wallust["Wallust<br/>palette generator<br/>[wallust.toml]"]
  node_matugen["Matugen<br/>palette generator<br/>[config.toml]"]
  node_theme_templates["Theme templates<br/>[templates]"]
end

subgraph group_interaction["Interaction"]
  node_hypr_scripts["Control scripts<br/>session scripts<br/>[scripts]"]
  node_hypr_user_scripts["User scripts<br/>session scripts<br/>[UserScripts]"]
  node_rofi["Rofi<br/>launcher ui<br/>[config.rasi]"]
end

subgraph group_status["Status"]
  node_waybar["Waybar<br/>status bar<br/>[config]"]
  node_swaync["SwayNC<br/>notifications<br/>[config.json]"]
  node_wlogout["Wlogout<br/>session menu<br/>[style.css]"]
end

subgraph group_media["Media"]
  node_mpd[("MPD<br/>music backend<br/>[mpd.conf]")]
  node_mpdris2["mpDris2<br/>media bridge<br/>[mpDris2.conf]"]
  node_rmpc["rmpc<br/>music client<br/>[config.ron]"]
  node_mpv["mpv<br/>video player<br/>[mpv.conf]"]
  node_spicetify["Spicetify<br/>spotify skin<br/>[config-xpui.ini]"]
end

subgraph group_productivity["Productivity"]
  node_kitty["Kitty<br/>terminal<br/>[kitty.conf]"]
  node_nvim["Neovim<br/>editor<br/>[init.lua]"]
  node_zsh_starship["Shell prompt<br/>shell config<br/>[starship.toml]"]
  node_apps_state[("App state<br/>runtime state<br/>[Seanime]")]
end

node_wallpaper_state -->|"feeds colors"| node_wallust
node_wallpaper_state -->|"feeds colors"| node_matugen
node_wallust -->|"renders"| node_theme_templates
node_matugen -->|"renders"| node_theme_templates
node_theme_templates -->|"styles"| node_hyprland
node_theme_templates -->|"styles"| node_kitty
node_theme_templates -->|"styles"| node_rofi
node_theme_templates -->|"styles"| node_waybar
node_theme_templates -->|"styles"| node_swaync
node_theme_templates -->|"styles"| node_spicetify
node_theme_templates -->|"styles"| node_zsh_starship
node_hyprland -->|"includes"| node_hypr_user_configs
node_hyprland -->|"includes"| node_hypr_configs
node_hyprland -->|"integrates"| node_pyprland
node_hyprland -->|"invokes"| node_hypr_scripts
node_hyprland -->|"invokes"| node_hypr_user_scripts
node_hyprland -->|"hosts"| node_waybar
node_hyprland -->|"hosts"| node_swaync
node_hyprland -->|"hosts"| node_wlogout
node_rofi -->|"launches"| node_hypr_scripts
node_hypr_scripts -->|"controls"| node_waybar
node_hypr_scripts -->|"opens"| node_wlogout
node_hypr_scripts -->|"controls"| node_mpd
node_mpdris2 -->|"bridges"| node_mpd
node_rmpc -->|"clients"| node_mpd
node_mpv -->|"controlled by"| node_hypr_scripts
node_spicetify -->|"themed by"| node_wallust
node_nvim -->|"paired with"| node_zsh_starship
node_apps_state -.->|"stores state"| node_spicetify
node_apps_state -.->|"stores state"| node_mpd
node_apps_state -.->|"stores state"| node_mpv

click node_hyprland "https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/hyprland.conf"
click node_hypr_user_configs "https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/UserConfigs"
click node_hypr_configs "https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/configs"
click node_hypr_scripts "https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/scripts"
click node_hypr_user_scripts "https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/UserScripts"
click node_pyprland "https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/pyprland.toml"
click node_wallpaper_state "https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/wallpaper_effects"
click node_wallust "https://github.com/nischaldawadi/hyprlust/blob/master/.config/wallust/wallust.toml"
click node_matugen "https://github.com/nischaldawadi/hyprlust/blob/master/.config/matugen/config.toml"
click node_theme_templates "https://github.com/nischaldawadi/hyprlust/blob/master/.config/wallust/templates"
click node_waybar "https://github.com/nischaldawadi/hyprlust/blob/master/.config/waybar/config"
click node_swaync "https://github.com/nischaldawadi/hyprlust/blob/master/.config/swaync/config.json"
click node_wlogout "https://github.com/nischaldawadi/hyprlust/blob/master/.config/wlogout/style.css"
click node_rofi "https://github.com/nischaldawadi/hyprlust/blob/master/.config/rofi/config.rasi"
click node_kitty "https://github.com/nischaldawadi/hyprlust/blob/master/.config/kitty/kitty.conf"
click node_nvim "https://github.com/nischaldawadi/hyprlust/blob/master/.config/nvim/init.lua"
click node_zsh_starship "https://github.com/nischaldawadi/hyprlust/blob/master/.config/starship.toml"
click node_mpd "https://github.com/nischaldawadi/hyprlust/blob/master/.config/mpd/mpd.conf"
click node_mpdris2 "https://github.com/nischaldawadi/hyprlust/blob/master/.config/mpDris2/mpDris2.conf"
click node_rmpc "https://github.com/nischaldawadi/hyprlust/blob/master/.config/rmpc/config.ron"
click node_mpv "https://github.com/nischaldawadi/hyprlust/blob/master/.config/mpv/mpv.conf"
click node_spicetify "https://github.com/nischaldawadi/hyprlust/blob/master/.config/spicetify/config-xpui.ini"
click node_apps_state "https://github.com/nischaldawadi/hyprlust/blob/master/.config/Seanime"

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_hyprland,node_hypr_user_configs,node_hypr_configs,node_pyprland toneBlue
class node_wallpaper_state,node_wallust,node_matugen,node_theme_templates toneAmber
class node_hypr_scripts,node_hypr_user_scripts,node_rofi toneMint
class node_waybar,node_swaync,node_wlogout toneRose
class node_mpd,node_mpdris2,node_rmpc,node_mpv,node_spicetify toneIndigo
class node_kitty,node_nvim,node_zsh_starship,node_apps_state toneTeal
```

## Components

### Session

Wayland session orchestration and Hyprland runtime

- [Hyprland](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/hyprland.conf): session compositor · Main Wayland session and window manager entrypoint · `.config/hypr/hyprland.conf`
- [User configs](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/UserConfigs): session config · Session settings, monitors, rules, startup apps, and keybinds · `.config/hypr/UserConfigs`
- [Core configs](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/configs): session config · Additional Hyprland settings and bind definitions · `.config/hypr/configs`
- [Pyprland](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/pyprland.toml): session plugins · Hyprland plugin/runtime integrations · `.config/hypr/pyprland.toml`

### Theming

Wallpaper-driven palette generation and desktop/app styling

- [Wallpaper state](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/wallpaper_effects): palette source · Current wallpaper and derived wallpaper-effects state · `.config/hypr/wallpaper_effects`
- [Wallust](https://github.com/nischaldawadi/hyprlust/blob/master/.config/wallust/wallust.toml): palette generator · Wallpaper-to-palette generation for desktop themes · `.config/wallust/wallust.toml`
- [Matugen](https://github.com/nischaldawadi/hyprlust/blob/master/.config/matugen/config.toml): palette generator · Theme token generation and template expansion · `.config/matugen/config.toml`
- [Theme templates](https://github.com/nischaldawadi/hyprlust/blob/master/.config/wallust/templates): theme templates · Shared templates that fan out colors into app-specific configs · `.config/wallust/templates`

### Interaction

Launchers, menus, and input-driven desktop actions

- [Control scripts](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/scripts): session scripts · Hyprland action scripts for system controls and desktop behavior · `.config/hypr/scripts`
- [User scripts](https://github.com/nischaldawadi/hyprlust/blob/master/.config/hypr/UserScripts): session scripts · User-facing scripts invoked from Hyprland and launchers · `.config/hypr/UserScripts`
- [Rofi](https://github.com/nischaldawadi/hyprlust/blob/master/.config/rofi/config.rasi): launcher ui · Launcher and menu entrypoints for desktop actions · `.config/rofi/config.rasi`

### Status

Bars, notifications, and session chrome

- [Waybar](https://github.com/nischaldawadi/hyprlust/blob/master/.config/waybar/config): status bar · Status bar layouts, styles, and generated colors · `.config/waybar/config`
- [SwayNC](https://github.com/nischaldawadi/hyprlust/blob/master/.config/swaync/config.json): notifications · Notification center and control-center styling · `.config/swaync/config.json`
- [Wlogout](https://github.com/nischaldawadi/hyprlust/blob/master/.config/wlogout/style.css): session menu · Logout and session power menu · `.config/wlogout/style.css`

### Media

Music and video playback stack

- [MPD](https://github.com/nischaldawadi/hyprlust/blob/master/.config/mpd/mpd.conf): music backend · Music daemon, database, playlists, and logs · `.config/mpd/mpd.conf`
- [mpDris2](https://github.com/nischaldawadi/hyprlust/blob/master/.config/mpDris2/mpDris2.conf): media bridge · Desktop control bridge for MPD playback · `.config/mpDris2/mpDris2.conf`
- [rmpc](https://github.com/nischaldawadi/hyprlust/blob/master/.config/rmpc/config.ron): music client · Terminal MPD client and theme config · `.config/rmpc/config.ron`
- [mpv](https://github.com/nischaldawadi/hyprlust/blob/master/.config/mpv/mpv.conf): video player · Media player with a layered Lua script stack · `.config/mpv/mpv.conf`
- [Spicetify](https://github.com/nischaldawadi/hyprlust/blob/master/.config/spicetify/config-xpui.ini): spotify skin · Spotify UI extraction, themes, and custom apps · `.config/spicetify/config-xpui.ini`

### Productivity

Terminal, editor, shell, and supporting apps

- [Kitty](https://github.com/nischaldawadi/hyprlust/blob/master/.config/kitty/kitty.conf): terminal · Terminal emulator theming and colors · `.config/kitty/kitty.conf`
- [Neovim](https://github.com/nischaldawadi/hyprlust/blob/master/.config/nvim/init.lua): editor · LazyVim-style editor configuration and plugins · `.config/nvim/init.lua`
- [Shell prompt](https://github.com/nischaldawadi/hyprlust/blob/master/.config/starship.toml): shell config · Zsh runtime and Starship prompt theming · `.config/starship.toml`
- [App state](https://github.com/nischaldawadi/hyprlust/blob/master/.config/Seanime): runtime state · Local caches, databases, and logs kept per application · `.config/Seanime`

## Connections

- Wallpaper state → Wallust: feeds colors · Wallpaper selection drives palette extraction
- Wallpaper state → Matugen: feeds colors · Wallpaper state also informs token generation
- Wallust → Theme templates: renders · Wallust fills shared theme templates
- Matugen → Theme templates: renders · Matugen expands templates for multiple targets
- Theme templates → Hyprland: styles · Generated colors flow into Hyprland visuals
- Theme templates → Kitty: styles · Terminal colors are generated from the palette pipeline
- Theme templates → Rofi: styles · Launcher themes are palette-driven
- Theme templates → Waybar: styles · Waybar styling and colors are generated here
- Theme templates → SwayNC: styles · Notification styling is palette-driven
- Theme templates → Spicetify: styles · Spotify theme assets consume generated colors
- Theme templates → Shell prompt: styles · Prompt theming follows the same palette source
- Hyprland → User configs: includes · Main session file assembles user-level configs
- Hyprland → Core configs: includes · Core settings and bind definitions are split out
- Hyprland → Pyprland: integrates · Plugin/runtime extensions augment the session
- Hyprland → Control scripts: invokes · Keybinds and actions call control scripts
- Hyprland → User scripts: invokes · User scripts provide higher-level desktop actions
- Hyprland → Waybar: hosts · Waybar is part of the session chrome
- Hyprland → SwayNC: hosts · Notification center attaches to the desktop session
- Hyprland → Wlogout: hosts · Logout UI is launched from the session
- Rofi → Control scripts: launches · Rofi menus are entry points for action scripts
- Control scripts → Waybar: controls · Scripts switch bar layouts and styles
- Control scripts → Wlogout: opens · Session scripts launch logout/power UI
- Control scripts → MPD: controls · Media-control scripts target the MPD backend
- mpDris2 → MPD: bridges · Exposes MPD to desktop controls and notifications
- rmpc → MPD: clients · Terminal client talks to MPD
- mpv → Control scripts: controlled by · Playback helpers and keybinds wrap mpv behavior
- Spicetify → Wallust: themed by · Spotify theming is aligned with the palette pipeline
- Neovim → Shell prompt: paired with · Editor and shell define the productivity environment
- App state → Spicetify: stores state · Spotify runtime artifacts live beside the themed config
- App state → MPD: stores state · Music daemon databases and playlists are local state
- App state → mpv: stores state · Player state, scripts, and subtitles are local runtime data
