# prodesquare/dotfiles architecture

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

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

## Overview

##### Project Type and Purpose
- This is a personal “dotfiles” repository for configuring an Arch/Artix Linux desktop environment. Its purpose is to store and manage configuration files and helper scripts for window management, shells, terminals, status bars, media players, editors, and other utilities.

##### File Structure Analysis
- Top-level directories:
- .config – application configuration (alacritty, bspwm, dunst, kitty, lf, mpd, mpv, ncmpcpp, neovim, picom, polybar, ranger, sxhkd, zathura, zsh, etc.)
- .local/bin – custom helper scripts (system info, statusbar modules, wallpaper, bspwm wrappers, screenshot tools)
- .local/share/applications – desktop file associations
- Key patterns:
- Window manager: .config/bspwm + .local/bin/bspwm
- Hotkey daemon: .config/sxhkd
- Shell: .zshrc, .zprofile, pathrc, aliasrc
- Status bar: scripts under .local/bin/statusbar and polybar config
- Editor: Neovim modular config in .config/neovim

##### README Insights
- Lists essential programs: DWM, sxhkd, ZSH
- Recommended tools: dwmblocks, dmenu, st, slock
- Others: MPD/NCMPCPP, MPV, Dunst, LF, Picom, Pipewire, etc.

##### Main Components
a. Core OS Layer
- Linux Kernel & X11/Wayland Server (initialized via .config/x11/xinitrc)
b. Window Management & Rendering
- bspwm (or DWM) ←→ sxhkd (hotkeys)
- picom (compositor)
c. Shell & Terminals
- ZSH (interactive shell)
- Terminal emulators: alacritty, kitty, st
d. Status & Notifications
- Status bar scripts (.local/bin/statusbar/*) → dwmblocks or polybar
- dunst (notification daemon)
e. User Applications
- File manager: lf
- Media: MPD + ncmpcpp, MPV, Spotify-TUI
- Editor: Neovim
- Utilities: scrot, feh, clipmenu, zathura, neomutt
f. Helper Scripts
- Custom scripts in .local/bin for brightness, screenshot, wallpaper, sysinfo, etc.
g. Desktop Integration
- .local/share/applications desktop entries

##### Relationships & Data Flows
- X11 Server ← user input → sxhkd → bspwm/DWM → windows
- Shell commands → custom scripts (.local/bin) → system/kernel calls (e.g., change brightness, fetch battery)
- Status scripts → statusbar → X11 → screen
- Applications request resources via OS and display on X11 under WM control
- Notification producers (e.g., battery script, MPD) → dunst

##### Architectural Patterns & Design Principles
- Unix philosophy: small, single-purpose tools (scripts and programs) orchestrated by shell and WM
- Layered design: Kernel → X11 → WM/compositor → user apps → dotfile-driven configuration
- Modularity: each program’s config lives in its own directory; statusbar comprises independent scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core OS Layer
    subgraph "Core OS Layer"
        Kernel["Linux Kernel"]:::core
        X11["X11 Server"]:::core
        ConfigX111["xinitrc"]:::config
        ConfigX112["xresources"]:::config
    end
    Kernel --> X11
    X11 --> ConfigX111
    X11 --> ConfigX112

    %% Window Management & Rendering
    subgraph "Window Management & Rendering"
        SXHKD["sxhkd (Hotkey Daemon)"]:::service
        BSPWM["bspwm (Window Manager)"]:::service
        Picom["picom (Compositor)"]:::service
        BSPWMConf["bspwmrc/noswallow/swallow/terminals"]:::config
        BSPWMScript[".local/bin/bspwm"]:::script
        BSPWMSwallow["bspswallow"]:::script
        SXHKDConf["sxhkdrc"]:::config
        PicomConf["picom.conf"]:::config
        PicomScript[".local/bin/compositor"]:::script
    end
    X11 --> SXHKD
    SXHKD --> BSPWM
    BSPWM --> Picom

    %% Shell & Terminals
    subgraph "Shell & Terminals"
        ZSH["ZSH Shell"]:::service
        ZSHRC[".zshrc/.zprofile/.zshenv"]:::config
        ShellIncludes["aliasrc/pathrc/promptrc/functionsrc"]:::config
        Alacritty["Alacritty"]:::app
        AlacrittyConf["alacritty.toml/themes"]:::config
        Kitty["Kitty"]:::app
        KittyConf["kitty.conf"]:::config
    end
    Kernel --> ZSH
    ZSH --> ShellIncludes
    ZSH --> ZSHRC
    ZSH --> Alacritty
    ZSH --> Kitty

    %% Status & Notifications
    subgraph "Status & Notifications"
        StatusScripts["Statusbar Scripts"]:::script
        Polybar["Polybar"]:::app
        PolybarConf["config.ini"]:::config
        Dunst["dunst"]:::service
        DunstConf["dunstrc"]:::config
    end
    StatusScripts --> Polybar
    Polybar --> X11
    Dunst --> X11

    %% User Applications
    subgraph "User Applications"
        LF["lf (File Manager)"]:::app
        LFConf["lfrc/cleaner/preview"]:::config
        MPD["MPD"]:::service
        MPDConf["mpd.conf"]:::config
        CMPCPP["ncmpcpp"]:::app
        MPV["MPV"]:::app
        MPVConf["mpv.conf/input.conf/subtitles.lua"]:::config
        Zathura["Zathura"]:::app
        ZathuraConf["zathurarc"]:::config
        Ranger["Ranger"]:::app
        RangerConf["rc.conf/rifle.conf/scope.sh"]:::config
        Neovim["Neovim"]:::app
        NeovimConf["modules/init/root dirs"]:::config
    end
    BSPWM --> LF
    BSPWM --> MPD
    BSPWM --> CMPCPP
    BSPWM --> MPV
    BSPWM --> Zathura
    BSPWM --> Ranger
    BSPWM --> Neovim

    %% Helper Scripts & Utilities
    subgraph "Helper Scripts & Utilities"
        Brightness["brightness"]:::script
        Sysinfo["sysinfo"]:::script
        Screenshot["screenshot"]:::script
        Wallpaper["wallpaper/setbg & setwall"]:::script
    end
    ZSH --> Brightness
    ZSH --> Sysinfo
    ZSH --> Screenshot
    ZSH --> Wallpaper

    %% Desktop Integration
    subgraph "Desktop Integration"
        FileDesktop["file.desktop"]:::config
        ImgDesktop["img.desktop"]:::config
        PdfDesktop["pdf.desktop"]:::config
        TextDesktop["text.desktop"]:::config
    end
    ApplicationsGroup(((Applications))):::group
    ApplicationsGroup --> FileDesktop
    ApplicationsGroup --> ImgDesktop
    ApplicationsGroup --> PdfDesktop
    ApplicationsGroup --> TextDesktop

    %% Click events
    click ConfigX111 "https://github.com/prodesquare/dotfiles/tree/master/.config/x11/xinitrc"
    click ConfigX112 "https://github.com/prodesquare/dotfiles/tree/master/.config/x11/xresources"
    click BSPWMConf "https://github.com/prodesquare/dotfiles/tree/master/.config/bspwm/bspwmrc"
    click BSPWMScript "https://github.com/prodesquare/dotfiles/tree/master/.local/bin/bspwm"
    click BSPWMSwallow "https://github.com/prodesquare/dotfiles/tree/master/.local/bin/bspwm/bspswallow"
    click SXHKDConf "https://github.com/prodesquare/dotfiles/tree/master/.config/sxhkd/sxhkdrc"
    click PicomConf "https://github.com/prodesquare/dotfiles/blob/master/.config/picom/picom.conf"
    click PicomScript "https://github.com/prodesquare/dotfiles/tree/master/.local/bin/compositor"
    click ZSHRC "https://github.com/prodesquare/dotfiles/blob/master/.config/zsh/.zshrc"
    click ShellIncludes "https://github.com/prodesquare/dotfiles/tree/master/.config/shell/aliasrc"
    click AlacrittyConf "https://github.com/prodesquare/dotfiles/blob/master/.config/alacritty/alacritty.toml"
    click KittyConf "https://github.com/prodesquare/dotfiles/blob/master/.config/kitty/kitty.conf"
    click PolybarConf "https://github.com/prodesquare/dotfiles/blob/master/.config/polybar/config.ini"
    click DunstConf "https://github.com/prodesquare/dotfiles/tree/master/.config/dunst/dunstrc"
    click LFConf "https://github.com/prodesquare/dotfiles/tree/master/.config/lf/lfrc"
    click MPDConf "https://github.com/prodesquare/dotfiles/blob/master/.config/mpd/mpd.conf"
    click MPVConf "https://github.com/prodesquare/dotfiles/blob/master/.config/mpv/mpv.conf"
    click ZathuraConf "https://github.com/prodesquare/dotfiles/tree/master/.config/zathura/zathurarc"
    click RangerConf "https://github.com/prodesquare/dotfiles/blob/master/.config/ranger/rc.conf"
    click NeovimConf "https://github.com/prodesquare/dotfiles/blob/master/.config/neovim/modules/init.lua"
    click Brightness "https://github.com/prodesquare/dotfiles/tree/master/.local/bin/brightness"
    click Sysinfo "https://github.com/prodesquare/dotfiles/tree/master/.local/bin/sysinfo"
    click Screenshot "https://github.com/prodesquare/dotfiles/tree/master/.local/bin/screenshot"
    click Wallpaper "https://github.com/prodesquare/dotfiles/tree/master/.local/bin/wallpaper/setbg"
    click FileDesktop "https://github.com/prodesquare/dotfiles/blob/master/.local/share/applications/file.desktop"

    %% Styles
    classDef core fill:#D6E9FA,stroke:#4A90E2,stroke-width:1px
    classDef app fill:#DFF2BF,stroke:#4CAF50,stroke-width:1px
    classDef service fill:#FEEFB3,stroke:#E6B800,stroke-width:1px
    classDef config fill:#EEEEEE,stroke:#999999,stroke-width:1px
    classDef script fill:#F7F7F7,stroke:#BBBBBB,stroke-width:1px
    classDef group fill:none,stroke:none
```
