# zproger/bspwm-dotfiles architecture

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

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

## Overview

##### Main Components

- Builder Module:
– Located in the “Builder” directory.
– Contains Python scripts (creators module with builder.py, drivers.py, patches.py, etc.), configuration options, installer (install.py), and logging (logger.py).
– Responsible for automatically installing packages, setting up drivers, and patching or customizing the system.

- Configuration Files:
– Found under the “config” directory.
– Contains subdirectories for each major application (Alacritty, bspwm, fish, polybar, redshift, etc.).
– Represents the core system configuration for the desktop environment.

- Custom Scripts & Utilities:
– The “bin” directory holds many shell scripts and Python utilities (e.g., battery-alert, brightness adjustment, wallpaper changer, etc.).
– These scripts provide additional runtime functionalities such as hotkeys, status alerts, and dynamic wallpapers.

- Themes & Assets:

- Documentation & Demonstration:
– “Docs” and “demonstration” directories store installation guides, feature documentation, and screenshots.

- External Configurations:
– Firefox custom configuration files and Xresources (for X11 resource settings) highlight customization of external applications.

##### Relationships and Interactions

- The Builder module acts as the orchestrator that reads configuration files, applies patches, and deploys scripts. Its creators scripts (like software.py, drivers.py, etc.) suggest layered responsibilities (such as handling software installation, configuring drivers, and applying system patches) that feed into the overall configuration.

- Custom scripts in the “bin” directory are designed to work with the installed desktop components – for example, hotkey scripts, wallpaper management, and system utilities – which in turn rely on the configurations specified in the “config” directory.

- Documentation (Docs) and demonstration images provide support and guidelines, feeding back into the Builder’s documentation for troubleshooting and feature explanations.

##### Architectural Patterns and Design Principles

- Automation & Customization: The Builder automates installation and system configuration which then connects to both system scripts and configuration files.
- Extensibility: With over 300 dynamic wallpapers and a wide array of customizable scripts, the project is designed to be easily extended.
- Separation between Core (configuration and theming) and Utility layers (installation scripts and custom scripts).

##### Including Relevant Technologies and Frameworks

- Base OS: Arch Linux
- Window Manager: bspwm
- Panel/Bar: Polybar
- Terminal Emulator: Alacritty
- Compositor: Picom
- Shell: Fish
- App Launcher: Rofi
- Notification Daemon: Dunst
- External integration for Firefox configuration, ranger (with plugins), and additional utilities in “bin”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Automation Layer
    subgraph "Build Automation Layer"
        BU("Builder Module\n(install.py, logger.py, creators/*)"):::builder
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        CF("Configuration Files\n(config/bspwm, polybar, alacritty, etc.)"):::config
    end

    %% Utility Scripts Layer
    subgraph "Utility Scripts Layer"
        CS("Custom Scripts & Utilities\n(bin/)"):::scripts
    end

    %% Asset & Theme Resources
    subgraph "Asset & Theme Resources"
        TA("Themes & Assets\n(themes, Icons, Images)"):::themes
    end

    %% Supporting Documentation & External Configurations
    subgraph "Supporting Docs & External Configs"
        DOC("Documentation & Demo Assets\n(Docs, demonstration)"):::docs
        EC1("Firefox Config"):::externalconf
        EC2("Xresources"):::externalconf
    end

    %% External Applications and Dependencies
    EA("External Applications\n(bspwm, polybar, alacritty, picom, rofi, dunst, etc.)"):::external

    %% Connections
    BU -->|"deploys"| CF
    BU -->|"applies"| EC1
    BU -->|"applies"| EC2
    BU -->|"orchestrates"| CS
    DOC -->|"guides"| BU
    TA -->|"styles"| CF
    CF -->|"feeds"| EA
    CS -->|"utilizes"| CF
    CS -->|"triggers"| EA
    EC1 -->|"configures"| EA

    %% Click Events
    click BU "https://github.com/zproger/bspwm-dotfiles/tree/main/Builder/"
    click CF "https://github.com/zproger/bspwm-dotfiles/tree/main/config/"
    click CS "https://github.com/zproger/bspwm-dotfiles/tree/main/bin/"
    click TA "https://github.com/zproger/bspwm-dotfiles/tree/main/themes/"
    click DOC "https://github.com/zproger/bspwm-dotfiles/tree/main/Docs/"
    click EC1 "https://github.com/zproger/bspwm-dotfiles/tree/main/firefox/"
    click EC2 "https://github.com/zproger/bspwm-dotfiles/tree/main/Xresources"

    %% Styles
    classDef builder fill:#85bb65,stroke:#333,stroke-width:2px;
    classDef config fill:#6baed6,stroke:#333,stroke-width:2px;
    classDef scripts fill:#fdae61,stroke:#333,stroke-width:2px;
    classDef themes fill:#fd8d3c,stroke:#333,stroke-width:2px;
    classDef docs fill:#bdbdbd,stroke:#333,stroke-width:2px;
    classDef externalconf fill:#9e9ac8,stroke:#333,stroke-width:2px;
    classDef external fill:#e377c2,stroke:#333,stroke-width:2px;
```
