# nakulbhat/dotfiles architecture

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

- Interactive diagram: https://gitdiagram.com/nakulbhat/dotfiles
- Repository: https://github.com/nakulbhat/dotfiles

## Overview

#### Purpose and Entry Points
This is a personal Linux desktop dotfiles repository centered on a NixOS host and Hyprland Wayland session. The primary system entry point is `nixos/configuration.nix`; user-session behavior is rooted in `hypr/hyprland.conf`. Application configuration is maintained directly in sibling directories and is expected to be linked or deployed into user config locations.

#### NixOS System Composition
`nixos/configuration.nix` defines the machine-level NixOS configuration and imports hardware settings from `nixos/hardware-configuration.nix`. It composes focused modules for installed applications, shell setup, user accounts, development tools, Python, Neovim, and Hyprland:
- `nixos/modules/apps.nix`
- `nixos/modules/users.nix`
- `nixos/modules/hyprland.nix`

This is the main declarative provisioning boundary: NixOS evaluates these modules to configure system packages, services, users, and desktop-session prerequisites.

#### Hyprland Desktop Session
`hypr/hyprland.conf` is the interactive compositor/session control plane: monitor, input, window-management, keybinding, and startup behavior belong here. Its commands delegate operational actions to scripts under `hypr/scripts/`, separating compositor policy from imperative desktop actions:
- `hypr/scripts/monitor_setup.sh`
- `hypr/scripts/runner.sh`
- `hypr/scripts/walls_randomiser.sh`

The session depends on Wayland-native desktop utilities configured elsewhere in the repository.

#### Desktop UI and Notification Boundary
The visible desktop shell is split across specialized processes:
- `waybar/config` and `waybar/style.css` define the status bar and presentation.
- `mako/config` configures notifications.
- `tofi/config` configures the application launcher.
- `hypr/hyprpaper.template` provides wallpaper configuration input.

`waybar/script.sh` is the notable bridge from status-bar configuration to shell-derived runtime data or actions.

#### Launcher and Device Automation Scripts
Hyprland bindings and launch actions invoke shell scripts that encapsulate environment-specific behavior. Terminal, editor, PDF, runner, monitor, wallpaper, and audio-output actions are independently scriptable:
- `hypr/scripts/term_launcher.sh`
- `hypr/scripts/nvim_launcher.sh`
- `hypr/scripts/switch_to_headphones.sh`

These scripts are an imperative boundary around external desktop tools and hardware/audio state; Hyprland remains the dispatcher.

#### Editor and Developer Environment
Neovim is configured as a Lua-based IDE. `nvim/init.lua` bootstraps editor configuration; `nvim/lua/config/lazy.lua` establishes plugin management, while LSP and plugin declarations define language tooling and completion:
- `nvim/lua/config/lsp.lua`
- `nvim/lua/plugins/core.lua`
- `nvim/lua/plugins/blink.lua`

System-level availability of Neovim and development dependencies is coordinated through `nixos/modules/neovim.nix`, `nixos/modules/dev-utils.nix`, and `nixos/modules/python-environment.nix`.

#### Terminal, Shell, and Document Clients
The user interaction layer uses Kitty, Zsh, Zathura, and Oh My Posh theme data:
- `kitty/kitty.conf`
- `zsh/.zshrc`
- `zathura/zathurarc`

These applications are configured independently but participate in the Hyprland session through launch scripts and NixOS-installed packages. The result is a NixOS-provisioned Wayland workstation whose runtime control flows from Hyprland bindings into dedicated scripts and configured desktop clients.

Main entry points: [`hypr/hyprland.conf`](https://github.com/nakulbhat/dotfiles/blob/main/hypr/hyprland.conf) (Hyprland configuration), [`nixos/configuration.nix`](https://github.com/nakulbhat/dotfiles/blob/main/nixos/configuration.nix) (NixOS configuration), [`nvim/init.lua`](https://github.com/nakulbhat/dotfiles/blob/main/nvim/init.lua) (Neovim bootstrap), [`nixos/modules/apps.nix`](https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/apps.nix) (Application packages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_nixos["NixOS provisioning"]
  node_nixos_config["NixOS configuration<br/>system entrypoint<br/>[configuration.nix]"]
  node_hardware["Hardware settings<br/>NixOS module"]
  node_apps_module["Application packages<br/>NixOS module<br/>[apps.nix]"]
  node_users_module["User accounts<br/>NixOS module<br/>[users.nix]"]
  node_hyprland_module["Hyprland prerequisites<br/>NixOS module<br/>[hyprland.nix]"]
  node_dev_modules["Development dependencies<br/>NixOS modules<br/>[dev-utils.nix]"]
end

subgraph group_session["Hyprland session"]
  node_hyprland_config["Hyprland configuration<br/>session entrypoint<br/>[hyprland.conf]"]
  node_hypr_scripts["Desktop action scripts<br/>shell scripts<br/>[runner.sh]"]
  node_wallpaper_template["Wallpaper input<br/>Hyprpaper template<br/>[hyprpaper.template]"]
end

subgraph group_desktop["Desktop clients"]
  node_waybar["Waybar<br/>status bar config"]
  node_waybar_script["Waybar runtime bridge<br/>shell script<br/>[script.sh]"]
  node_mako["Mako<br/>notification config"]
  node_tofi["Tofi<br/>launcher config"]
  node_terminal_shell["Terminal and shell<br/>client configs<br/>[kitty.conf]"]
  node_zathura["Zathura<br/>document client config"]
end

subgraph group_editor["Editor environment"]
  node_nvim_init["Neovim bootstrap<br/>Lua entrypoint<br/>[init.lua]"]
  node_lazy_config["Plugin manager<br/>Neovim Lua config<br/>[lazy.lua]"]
  node_lsp_config["LSP tooling<br/>Neovim Lua config<br/>[lsp.lua]"]
  node_plugin_specs["Core and completion plugins<br/>Neovim plugin specs<br/>[core.lua]"]
end

node_nixos_config -->|"imports"| node_hardware
node_nixos_config -->|"composes"| node_apps_module
node_nixos_config -->|"composes"| node_users_module
node_nixos_config -->|"enables"| node_hyprland_module
node_nixos_config -->|"provisions"| node_dev_modules
node_hyprland_module -->|"supports session"| node_hyprland_config
node_apps_module -.->|"provides package"| node_waybar
node_apps_module -.->|"provides package"| node_mako
node_apps_module -.->|"provides package"| node_tofi
node_hyprland_config -->|"dispatches actions"| node_hypr_scripts
node_hyprland_config -->|"starts desktop bar"| node_waybar
node_hyprland_config -->|"uses notifications"| node_mako
node_hyprland_config -->|"opens launcher"| node_tofi
node_hyprland_config -->|"uses wallpaper input"| node_wallpaper_template
node_hypr_scripts -->|"launches terminal"| node_terminal_shell
node_hypr_scripts -->|"launches editor"| node_nvim_init
node_hypr_scripts -->|"launches PDF client"| node_zathura
node_waybar -->|"executes"| node_waybar_script
node_dev_modules -.->|"provides runtime"| node_nvim_init
node_nvim_init -->|"bootstraps"| node_lazy_config
node_nvim_init -->|"loads"| node_lsp_config
node_nvim_init -->|"loads"| node_plugin_specs

click node_nixos_config "https://github.com/nakulbhat/dotfiles/blob/main/nixos/configuration.nix"
click node_hardware "https://github.com/nakulbhat/dotfiles/blob/main/nixos/hardware-configuration.nix"
click node_apps_module "https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/apps.nix"
click node_users_module "https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/users.nix"
click node_hyprland_module "https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/hyprland.nix"
click node_dev_modules "https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/dev-utils.nix"
click node_hyprland_config "https://github.com/nakulbhat/dotfiles/blob/main/hypr/hyprland.conf"
click node_hypr_scripts "https://github.com/nakulbhat/dotfiles/blob/main/hypr/scripts/runner.sh"
click node_wallpaper_template "https://github.com/nakulbhat/dotfiles/blob/main/hypr/hyprpaper.template"
click node_waybar "https://github.com/nakulbhat/dotfiles/blob/main/waybar/config"
click node_waybar_script "https://github.com/nakulbhat/dotfiles/blob/main/waybar/script.sh"
click node_mako "https://github.com/nakulbhat/dotfiles/blob/main/mako/config"
click node_tofi "https://github.com/nakulbhat/dotfiles/blob/main/tofi/config"
click node_terminal_shell "https://github.com/nakulbhat/dotfiles/blob/main/kitty/kitty.conf"
click node_zathura "https://github.com/nakulbhat/dotfiles/blob/main/zathura/zathurarc"
click node_nvim_init "https://github.com/nakulbhat/dotfiles/blob/main/nvim/init.lua"
click node_lazy_config "https://github.com/nakulbhat/dotfiles/blob/main/nvim/lua/config/lazy.lua"
click node_lsp_config "https://github.com/nakulbhat/dotfiles/blob/main/nvim/lua/config/lsp.lua"
click node_plugin_specs "https://github.com/nakulbhat/dotfiles/blob/main/nvim/lua/plugins/core.lua"

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_nixos_config,node_hardware,node_apps_module,node_users_module,node_hyprland_module,node_dev_modules toneBlue
class node_hyprland_config,node_hypr_scripts,node_wallpaper_template toneAmber
class node_waybar,node_waybar_script,node_mako,node_tofi,node_terminal_shell,node_zathura toneMint
class node_nvim_init,node_lazy_config,node_lsp_config,node_plugin_specs toneRose
```

## Components

### NixOS provisioning

Declarative machine and package setup.

- [NixOS configuration](https://github.com/nakulbhat/dotfiles/blob/main/nixos/configuration.nix): system entrypoint · Composes host modules and hardware settings. · `nixos/configuration.nix`
- [Hardware settings](https://github.com/nakulbhat/dotfiles/blob/main/nixos/hardware-configuration.nix): NixOS module · `nixos/hardware-configuration.nix`
- [Application packages](https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/apps.nix): NixOS module · `nixos/modules/apps.nix`
- [User accounts](https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/users.nix): NixOS module · `nixos/modules/users.nix`
- [Hyprland prerequisites](https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/hyprland.nix): NixOS module · `nixos/modules/hyprland.nix`
- [Development dependencies](https://github.com/nakulbhat/dotfiles/blob/main/nixos/modules/dev-utils.nix): NixOS modules · Provides developer, Python, and Neovim dependencies. · `nixos/modules/dev-utils.nix`

### Hyprland session

Wayland compositor policy and operational actions.

- [Hyprland configuration](https://github.com/nakulbhat/dotfiles/blob/main/hypr/hyprland.conf): session entrypoint · Controls compositor policy, bindings, and startup. · `hypr/hyprland.conf`
- [Desktop action scripts](https://github.com/nakulbhat/dotfiles/blob/main/hypr/scripts/runner.sh): shell scripts · Launchers and monitor, wallpaper, and audio actions. · `hypr/scripts/runner.sh`
- [Wallpaper input](https://github.com/nakulbhat/dotfiles/blob/main/hypr/hyprpaper.template): Hyprpaper template · `hypr/hyprpaper.template`

### Desktop clients

Independent user-facing Wayland application configuration.

- [Waybar](https://github.com/nakulbhat/dotfiles/blob/main/waybar/config): status bar config · Status bar configuration and styling. · `waybar/config`
- [Waybar runtime bridge](https://github.com/nakulbhat/dotfiles/blob/main/waybar/script.sh): shell script · Supplies shell-derived status data or actions. · `waybar/script.sh`
- [Mako](https://github.com/nakulbhat/dotfiles/blob/main/mako/config): notification config · `mako/config`
- [Tofi](https://github.com/nakulbhat/dotfiles/blob/main/tofi/config): launcher config · `tofi/config`
- [Terminal and shell](https://github.com/nakulbhat/dotfiles/blob/main/kitty/kitty.conf): client configs · Kitty and Zsh user interaction environment. · `kitty/kitty.conf`
- [Zathura](https://github.com/nakulbhat/dotfiles/blob/main/zathura/zathurarc): document client config · `zathura/zathurarc`

### Editor environment

Neovim configuration and language tooling.

- [Neovim bootstrap](https://github.com/nakulbhat/dotfiles/blob/main/nvim/init.lua): Lua entrypoint · Initializes the Lua-based IDE configuration. · `nvim/init.lua`
- [Plugin manager](https://github.com/nakulbhat/dotfiles/blob/main/nvim/lua/config/lazy.lua): Neovim Lua config · `nvim/lua/config/lazy.lua`
- [LSP tooling](https://github.com/nakulbhat/dotfiles/blob/main/nvim/lua/config/lsp.lua): Neovim Lua config · `nvim/lua/config/lsp.lua`
- [Core and completion plugins](https://github.com/nakulbhat/dotfiles/blob/main/nvim/lua/plugins/core.lua): Neovim plugin specs · `nvim/lua/plugins/core.lua`

## Connections

- NixOS configuration → Hardware settings: imports
- NixOS configuration → Application packages: composes
- NixOS configuration → User accounts: composes
- NixOS configuration → Hyprland prerequisites: enables
- NixOS configuration → Development dependencies: provisions
- Hyprland prerequisites → Hyprland configuration: supports session
- Application packages → Waybar: provides package
- Application packages → Mako: provides package
- Application packages → Tofi: provides package
- Hyprland configuration → Desktop action scripts: dispatches actions
- Hyprland configuration → Waybar: starts desktop bar
- Hyprland configuration → Mako: uses notifications
- Hyprland configuration → Tofi: opens launcher
- Hyprland configuration → Wallpaper input: uses wallpaper input
- Desktop action scripts → Terminal and shell: launches terminal
- Desktop action scripts → Neovim bootstrap: launches editor
- Desktop action scripts → Zathura: launches PDF client
- Waybar → Waybar runtime bridge: executes
- Development dependencies → Neovim bootstrap: provides runtime
- Neovim bootstrap → Plugin manager: bootstraps
- Neovim bootstrap → LSP tooling: loads
- Neovim bootstrap → Core and completion plugins: loads