# rommmmaha/dotfiles architecture

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

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

## Overview

1. **What this repo is**
   - This is a **home-directory dotfiles repository** for a **CachyOS / Arch-based Linux desktop**, managed with **chezmoi**.
   - The repo is not an app codebase; it is a **configuration distribution system** that materializes files into `~/.config`, `~/.local`, shell startup files, and other user-level locations.

2. **Primary deployment model**
   - The source of truth lives in the repo, and chezmoi applies it into the user’s home directory.
   - Files named with prefixes like `dot_config`, `dot_local`, `dot_zshrc`, `dot_bashrc`, etc. map to their target paths under `$HOME`.
   - Template files (`*.tmpl`) indicate **rendered configuration** with machine-specific or environment-specific values injected at apply time.

3. **Configuration orchestration layer**
   - `.chezmoi.toml.tmpl` likely defines chezmoi behavior and host-specific variables.
   - `.chezmoiscripts/` contains **post-apply hooks** that run after synchronization, used to refresh stateful desktop components.
   - This gives the repo a two-stage flow: **render files → run follow-up actions**.

4. **Package baseline and system dependencies**
   - `packages.txt` is the package manifest for the desktop environment.
   - The README shows packages are installed via `yay`, so the repo assumes an **Arch/AUR package workflow**.
   - The repo depends on external system packages for its full behavior; the dotfiles configure them rather than vendor them.

5. **Shell and session initialization**
   - `dot_bashrc`, `dot_zshrc`, and `dot_zprofile` define the interactive shell/session layer.
   - `starship.toml.tmpl`, `direnv/direnv.toml`, `bat/config`, `btop/btop.conf`, and `micro/*` support a **CLI-first workflow**.
   - This layer is the user-facing entry point for terminal environment setup and prompt/tool behavior.

6. **Wayland desktop stack**
   - The core desktop subsystem is **Hyprland** under `dot_config/hypr/`.
   - Related components include:
     - `hyprpaper` for wallpaper management,
     - `hyprlock` for lock screen,
     - `eww` for custom desktop widgets,
     - `rofi` and `rofimoji` for launchers/pickers,
     - `swaync` for notifications,
     - `xdg-desktop-portal/hyprland-portals.conf` for desktop integration.
   - This forms the main graphical control plane around the compositor.

7. **Host-specific window-manager behavior**
   - `dot_config/hypr/custom/hyprland-laptop.conf` and `hyprland-pc.conf` split the desktop config by device class.
   - `application-style.conf`, `_ws.sh`, and `executable__clipvault.sh` suggest custom Hyprland helpers for workspace behavior and app-specific automation.
   - This indicates the repo supports **multiple hardware profiles** with shared base config plus overrides.

8. **Audio, media, and screen-related subsystems**
   - `pipewire/conf.d/*` configures the audio stack, including realtime settings, larger quantum, loopbacks, and virtual sinks.
   - `mpv` configures media playback behavior.
   - `flameshot` supports screenshots/annotations, and the custom local scripts include `r_sndcpy.py`, suggesting additional audio/video utility glue.
   - These configs indicate the repo tunes multimedia behavior beyond defaults.

9. **Theme and visual consistency**
   - GTK theming is handled by `gtk-3.0/gtk.css`, `gtk-4.0/gtk.css`, and `qt6engine` integration via Hyprland config.
   - `fastfetch/simple.jsonc`, `BreezeMidnight.colors`, `wallpaper/`, and `eww.scss` contribute to the desktop’s visual identity.
   - The repo treats appearance as a cross-application concern, not a single-tool concern.

10. **System and desktop integration boundaries**
   - `systemd/user.conf` configures user-session behavior.
   - `hblock/allow.list` suggests ad/tracker blocking integration at the DNS/hosts layer.
   - `yay/config.json.tmpl` and `gitconfig` support package and source control workflows.
   - The README also calls out several **manual system-wide settings** under `/etc`, which are explicitly outside chezmoi’s managed scope.

11. **Local user scripts and executables**
   - `dot_local/bin/` contains user-owned executable helpers, including `r_game.py` and `r_sndcpy.py`.
   - These are part of the personalized automation/tooling layer and likely consumed from shell or desktop launchers.
   - `dot_local/share/...` stores per-user data assets such as color schemes.

12. **Operational flow to keep in mind**
   - The repo is applied with chezmoi, packages are installed separately with `yay`, and some services/configs are then refreshed via post-apply scripts.
   - The architecture is therefore: **repo source → chezmoi-rendered home config → installed system packages/services → live desktop session**.
   - Anything listed in the README as `/etc` edits is a deliberate boundary: it supports the environment but is not managed by this repo.

Main entry points: [`dot_config/hypr/hyprland.conf.tmpl`](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/hypr/hyprland.conf.tmpl) (Hyprland core), [`.chezmoi.toml.tmpl`](https://github.com/rommmmaha/dotfiles/blob/master/.chezmoi.toml.tmpl) (chezmoi config), [`.chezmoiscripts`](https://github.com/rommmmaha/dotfiles/blob/master/.chezmoiscripts) (apply hooks), [`dot_config/starship.toml.tmpl`](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/starship.toml.tmpl) (prompt setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_orchestration["Orchestration"]
  node_n1["chezmoi config<br/>template<br/>[.chezmoi.toml.tmpl]"]
  node_n2["apply hooks<br/>post-apply scripts<br/>[.chezmoiscripts]"]
end

subgraph group_group_shell["Shell & CLI"]
  node_n4["bash startup<br/>shell init"]
  node_n5["zsh startup<br/>shell init"]
  node_n6["zprofile<br/>shell login"]
  node_n7["prompt setup<br/>prompt config<br/>[starship.toml.tmpl]"]
  node_n8["CLI tools<br/>editor+terminal config"]
end

subgraph group_group_desktop["Desktop Stack"]
  node_n9["Hyprland core<br/>compositor config<br/>[hyprland.conf.tmpl]"]
  node_n10["Hypr helpers<br/>hypr scripts"]
  node_n11["lock & wallpaper<br/>session utilities<br/>[hyprlock.conf]"]
  node_n12["widgets & notifications<br/>desktop UI"]
  node_n13["launchers<br/>rofi config"]
  node_n14["theme system<br/>appearance<br/>[gtk.css]"]
  node_n15["audio stack<br/>pipewire tuning<br/>[pipewire.conf.d]"]
  node_n16["media & screenshots<br/>media tools"]
end

subgraph group_group_system["System Integration"]
  node_n3["package manifest<br/>package list<br/>[packages.txt]"]
  node_n17["session integration<br/>integration config"]
  node_n18["package manager<br/>yay config<br/>[config.json.tmpl]"]
end

subgraph group_group_local["Local Assets"]
  node_n19["local executables<br/>user scripts"]
  node_n20["color assets<br/>theme assets"]
end

node_n1 -->|"renders"| node_n9
node_n1 -->|"renders"| node_n7
node_n1 -->|"renders"| node_n18
node_n1 -->|"renders"| node_n16
node_n1 -->|"renders"| node_n14
node_n1 -->|"renders"| node_n17
node_n1 -->|"describes"| node_n3
node_n2 -->|"refreshes"| node_n9
node_n2 -->|"refreshes"| node_n11
node_n2 -->|"refreshes"| node_n12
node_n2 -->|"refreshes"| node_n13
node_n3 -->|"feeds"| node_n18
node_n4 -->|"uses"| node_n7
node_n5 -->|"uses"| node_n7
node_n6 -->|"uses"| node_n7
node_n8 -->|"supports"| node_n4
node_n8 -->|"supports"| node_n5
node_n9 -->|"includes"| node_n10
node_n9 -->|"coordinates"| node_n11
node_n9 -->|"coordinates"| node_n12
node_n9 -->|"coordinates"| node_n13
node_n9 -->|"depends on"| node_n15
node_n14 -->|"shares"| node_n20
node_n15 -->|"supports"| node_n16
node_n17 -->|"integrates"| node_n9
node_n19 -->|"invokes"| node_n10
node_n19 -->|"supports"| node_n16

click node_n1 "https://github.com/rommmmaha/dotfiles/blob/master/.chezmoi.toml.tmpl"
click node_n2 "https://github.com/rommmmaha/dotfiles/blob/master/.chezmoiscripts"
click node_n3 "https://github.com/rommmmaha/dotfiles/blob/master/packages.txt"
click node_n4 "https://github.com/rommmmaha/dotfiles/tree/master/dot_bashrc"
click node_n5 "https://github.com/rommmmaha/dotfiles/tree/master/dot_zshrc"
click node_n6 "https://github.com/rommmmaha/dotfiles/tree/master/dot_zprofile"
click node_n7 "https://github.com/rommmmaha/dotfiles/blob/master/dot_config/starship.toml.tmpl"
click node_n8 "https://github.com/rommmmaha/dotfiles/tree/master/dot_config"
click node_n9 "https://github.com/rommmmaha/dotfiles/blob/master/dot_config/hypr/hyprland.conf.tmpl"
click node_n10 "https://github.com/rommmmaha/dotfiles/tree/master/dot_config/hypr/custom"
click node_n11 "https://github.com/rommmmaha/dotfiles/blob/master/dot_config/hypr/hyprlock.conf"
click node_n12 "https://github.com/rommmmaha/dotfiles/tree/master/dot_config/eww"
click node_n13 "https://github.com/rommmmaha/dotfiles/tree/master/dot_config/rofi"
click node_n14 "https://github.com/rommmmaha/dotfiles/blob/master/dot_config/gtk-3.0/gtk.css"
click node_n15 "https://github.com/rommmmaha/dotfiles/blob/master/dot_config/pipewire/pipewire.conf.d"
click node_n16 "https://github.com/rommmmaha/dotfiles/tree/master/dot_config/mpv"
click node_n17 "https://github.com/rommmmaha/dotfiles/blob/master/dot_config/xdg-desktop-portal/hyprland-portals.conf"
click node_n18 "https://github.com/rommmmaha/dotfiles/blob/master/dot_config/yay/config.json.tmpl"
click node_n19 "https://github.com/rommmmaha/dotfiles/tree/master/dot_local/bin"
click node_n20 "https://github.com/rommmmaha/dotfiles/blob/master/dot_local/share/color-schemes/BreezeMidnight.colors"

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_n1,node_n2 toneBlue
class node_n4,node_n5,node_n6,node_n7,node_n8 toneAmber
class node_n9,node_n10,node_n11,node_n12,node_n13,node_n14,node_n15,node_n16 toneMint
class node_n3,node_n17,node_n18 toneRose
class node_n19,node_n20 toneIndigo
```

## Components

### Orchestration

chezmoi-driven application and post-apply hooks

- [chezmoi config](https://github.com/rommmmaha/dotfiles/blob/master/.chezmoi.toml.tmpl): template · Top-level chezmoi behavior and host variables · `.chezmoi.toml.tmpl`
- [apply hooks](https://github.com/rommmmaha/dotfiles/blob/master/.chezmoiscripts): post-apply scripts · Runs follow-up actions after syncing dotfiles · `.chezmoiscripts`

### Shell & CLI

Interactive shell, terminal, and CLI tooling

- [bash startup](https://github.com/rommmmaha/dotfiles/tree/master/dot_bashrc): shell init · Bash session initialization · `dot_bashrc`
- [zsh startup](https://github.com/rommmmaha/dotfiles/tree/master/dot_zshrc): shell init · Zsh login and interactive initialization · `dot_zshrc`
- [zprofile](https://github.com/rommmmaha/dotfiles/tree/master/dot_zprofile): shell login · Login-shell environment setup · `dot_zprofile`
- [prompt setup](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/starship.toml.tmpl): prompt config · Cross-shell prompt rendering · `dot_config/starship.toml.tmpl`
- [CLI tools](https://github.com/rommmmaha/dotfiles/tree/master/dot_config): editor+terminal config · Terminal, editor, and command-line workflow settings · `dot_config`

### Desktop Stack

Hyprland-based Wayland session and related UI components

- [Hyprland core](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/hypr/hyprland.conf.tmpl): compositor config · Primary Wayland compositor and session control plane · `dot_config/hypr/hyprland.conf.tmpl`
- [Hypr helpers](https://github.com/rommmmaha/dotfiles/tree/master/dot_config/hypr/custom): hypr scripts · Workspace and app automation helpers · `dot_config/hypr/custom`
- [lock & wallpaper](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/hypr/hyprlock.conf): session utilities · Lock screen and wallpaper management · `dot_config/hypr/hyprlock.conf`
- [widgets & notifications](https://github.com/rommmmaha/dotfiles/tree/master/dot_config/eww): desktop UI · Custom widgets and notification styling · `dot_config/eww`
- [launchers](https://github.com/rommmmaha/dotfiles/tree/master/dot_config/rofi): rofi config · Application launcher and emoji picker configuration · `dot_config/rofi`
- [theme system](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/gtk-3.0/gtk.css): appearance · Cross-application theming and visual identity · `dot_config/gtk-3.0/gtk.css`
- [audio stack](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/pipewire/pipewire.conf.d): pipewire tuning · Realtime, quantum, virtual sinks, and loopbacks · `dot_config/pipewire/pipewire.conf.d`
- [media & screenshots](https://github.com/rommmmaha/dotfiles/tree/master/dot_config/mpv): media tools · Media playback and screenshot workflow settings · `dot_config/mpv`

### System Integration

Package baseline and session-level integration points

- [package manifest](https://github.com/rommmmaha/dotfiles/blob/master/packages.txt): package list · Baseline packages for the desktop environment · `packages.txt`
- [session integration](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/xdg-desktop-portal/hyprland-portals.conf): integration config · Desktop portal, user services, and content blocking support · `dot_config/xdg-desktop-portal/hyprland-portals.conf`
- [package manager](https://github.com/rommmmaha/dotfiles/blob/master/dot_config/yay/config.json.tmpl): yay config · AUR/package workflow configuration · `dot_config/yay/config.json.tmpl`

### Local Assets

User-owned scripts and shared data

- [local executables](https://github.com/rommmmaha/dotfiles/tree/master/dot_local/bin): user scripts · Personal automation and helper programs · `dot_local/bin`
- [color assets](https://github.com/rommmmaha/dotfiles/blob/master/dot_local/share/color-schemes/BreezeMidnight.colors): theme assets · User-shared color schemes and palette data · `dot_local/share/color-schemes/BreezeMidnight.colors`

## Connections

- chezmoi config → Hyprland core: renders · chezmoi materializes compositor config
- chezmoi config → prompt setup: renders · renders prompt template
- chezmoi config → package manager: renders · renders package-manager config
- chezmoi config → media & screenshots: renders · renders media configuration
- chezmoi config → theme system: renders · renders theme-related files
- chezmoi config → session integration: renders · renders integration config
- chezmoi config → package manifest: describes · package baseline is tracked alongside dotfiles
- apply hooks → Hyprland core: refreshes · post-apply hooks reload desktop state
- apply hooks → lock & wallpaper: refreshes · reloads wallpaper/lockscreen state
- apply hooks → widgets & notifications: refreshes · restarts widget-related state
- apply hooks → launchers: refreshes · updates launcher-dependent state
- package manifest → package manager: feeds · package workflow depends on baseline manifest
- bash startup → prompt setup: uses · shell startup picks up prompt tooling
- zsh startup → prompt setup: uses · zsh startup picks up prompt tooling
- zprofile → prompt setup: uses · login shell layers into prompt setup
- CLI tools → bash startup: supports · CLI tooling is surfaced from shell init
- CLI tools → zsh startup: supports · CLI tooling is surfaced from shell init
- Hyprland core → Hypr helpers: includes · core compositor config references custom helpers
- Hyprland core → lock & wallpaper: coordinates · compositor session ties into lock and wallpaper
- Hyprland core → widgets & notifications: coordinates · compositor drives widget/notification layer
- Hyprland core → launchers: coordinates · compositor launches rofi-based tools
- Hyprland core → audio stack: depends on · desktop session relies on tuned audio stack
- theme system → color assets: shares · theme system reuses palette assets
- audio stack → media & screenshots: supports · audio/video configs depend on PipeWire tuning
- session integration → Hyprland core: integrates · portal integration is tied to Hyprland session
- local executables → Hypr helpers: invokes · local executables are used by compositor helpers
- local executables → media & screenshots: supports · custom scripts support media-related workflows
