# ugase/dotfiles architecture

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

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

## Overview

##### Project Type and Purpose
- This is an open-source “dotfiles” repository—a configuration management toolkit for a Linux desktop environment. It bundles shell configurations (Zsh, tmux), editor settings (Neovim), terminal emulators (Alacritty, Foot), window manager configs (Sway, Waybar), plus themes and helper scripts.
- Its main use case is “clone & install” via a single shell command: install system packages, clone the repo, run stow to symlink configs into the user’s home directory, and bootstrap auxiliary tooling (yay, oh-my-posh, fastfetch).

##### File Structure Analysis
- Top-level:
- `.config/`   – application config directories
- `README.md` – install instructions
- `crontabs/` – scheduled scripts
- shell files (`.zshrc`, `.zshenv`, `alias.zsh`, `funcs.zsh`)
- `Wallpapers/` – assets
- `kanata/` – custom keyboard layout
- Under `.config/` each app (alacritty, nvim, sway, tmux, waybar, foot) has its own directory.
- Neovim uses a modular `lua/` directory for plugins & options.
- There is a `stow`-based layout: each top-level file or folder corresponds to a stow package.

##### Key Insights from the README
- Single big install command:
- Installs system packages via pacman & yay
- Clones dotfiles repository
- Builds and installs AUR helper (yay)
- Installs extra tools (oh-my-posh, fastfetch)
- Runs `stow --adopt` to create all symlinks
- Cleans up clone & temporary files

##### Main Components
a. Dotfiles Repository
– Contains stow packages (each top-level folder/file)
– Install scripts (`crontabs/*.sh`)
b. Shell Orchestrator
– User shell (Zsh) running the install command
– stow as symlink manager
c. Package Managers
– pacman (official packages)
– git (cloning)
– yay (AUR helper)
d. External Tools & Services
– oh-my-posh, fastfetch (installed via yay)
– AUR & Arch Linux repos
e. User Home Directory
– Final symlinked config files under `$HOME/.config/...` and dotfiles like `~/.zshrc`, `~/.tmux.conf`

##### Relationships & Data Flows
- User invokes install script → pacman & yay install required packages
- Script clones Git repo → stow reads packages → stow creates symlinks into `$HOME`
- Additional scripts (crontabs) get installed to scheduling system
- External tools (oh-my-posh, fastfetch) integrate into shell prompt & system info display

##### Architectural Patterns & Design Principles
- Modular configuration via GNU stow (one directory = one package)
- Declarative list of dependencies in a single shell orchestration line
- Separation of concerns:
- Package installation
- File provisioning (stow)
- Schedule automation (crontabs)
- Extensibility: add new `.config/appname` or top-level file and stow picks it up.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Invocation
    User["User"]:::actor -->|1. run install| README

    %% Dotfiles Repository and Scripts
    subgraph "Dotfiles Repository" 
        direction TB
        RepoRoot["/ (stow packages root)"]:::repo
        README["README.md"]:::script
        ZshEnv[".zshenv"]:::config
        ZshRC[".zshrc"]:::config
        AliasZsh["alias.zsh"]:::config
        FuncsZsh["funcs.zsh"]:::config
        subgraph "tmux Config"
            TMUXConf[".tmux/tmux.conf"]:::config
            TMUXPlugins[".tmux/plugins/"]:::config
        end
        subgraph "Alacritty Config"
            AlacrittyToml[".config/alacritty/alacritty.toml"]:::config
            AlacrittyThemes[".config/alacritty/themes/"]:::config
        end
        FootIni[".config/foot/foot.ini"]:::config
        subgraph "Neovim Config"
            NVIMInit[".config/nvim/init.lua"]:::config
            NVIMOptions[".config/nvim/lua/options.lua"]:::config
            NVIMMappings[".config/nvim/lua/mappings.lua"]:::config
            NVIMPlugins[".config/nvim/lua/plugins/"]:::config
            NVIMStyLua[".config/nvim/stylua.toml"]:::config
        end
        SwayConfig[".config/sway/config"]:::config
        subgraph "Waybar Config"
            WaybarConfig[".config/waybar/config.jsonc"]:::config
            WaybarStyle[".config/waybar/style.css"]:::config
        end
        OMPConfig[".config/omp/config.toml"]:::config
        FastfetchConfig[".config/fastfetch/config.jsonc"]:::config
        subgraph "Crontabs"
            CronDot["crontabs/dot.sh"]:::script
            CronUpdate["crontabs/update_index.sh"]:::script
        end
        subgraph "Assets & Layout"
            Wallpapers["Wallpapers/contents/"]:::assets
            Kanata["kanata/kanta.kbd"]:::assets
        end
        StowIgnore[".stow-local-ignore"]:::repo
    end

    %% Package Managers and External Tools
    subgraph "Package Managers" 
        direction TB
        Pacman["pacman"]:::pkg
        Git["git"]:::pkg
        Yay["yay"]:::pkg
    end

    subgraph "External Tools"
        direction TB
        OhMyPosh["oh-my-posh"]:::ext
        Fastfetch["fastfetch"]:::ext
    end

    Scheduler["OS Scheduler (cron)"]:::pkg
    HomeFS["User Home FS"]:::home

    %% Data Flow
    README -->|install| Pacman
    README -->|install| Yay
    README -->|clone repo| Git
    Git -->|clones| RepoRoot
    README -->|run stow| Stow
    subgraph "Symlink Provisioning"
        direction TB
        Stow["stow"]:::repo -->|symlink| HomeFS
    end
    README -->|install scripts| Scheduler
    README -->|install ext tools| Yay
    Yay -->|installs| OhMyPosh
    Yay -->|installs| Fastfetch
    OhMyPosh -->|configs| HomeFS
    Fastfetch -->|configs| HomeFS

    %% Legend via implicit class definitions
    classDef repo fill:#e0f7fa,stroke:#0288d1,color:#000
    classDef script fill:#e1f5fe,stroke:#01579b,color:#000
    classDef pkg fill:#e8f5e9,stroke:#2e7d32,color:#000
    classDef config fill:#fff9c4,stroke:#f9a825,color:#000
    classDef ext fill:#ffecb3,stroke:#ef6c00,color:#000
    classDef assets fill:#fce4ec,stroke:#ad1457,color:#000
    classDef home fill:#e8eaf6,stroke:#303f9f,color:#000
    classDef actor fill:#c8e6c9,stroke:#388e3c,color:#000

    %% Click Events
    click RepoRoot "https://github.com/ugase/dotfiles/tree/master//"
    click README "https://github.com/ugase/dotfiles/blob/master/README.md"
    click ZshEnv "https://github.com/ugase/dotfiles/blob/master/.zshenv"
    click ZshRC "https://github.com/ugase/dotfiles/blob/master/.zshrc"
    click AliasZsh "https://github.com/ugase/dotfiles/blob/master/alias.zsh"
    click FuncsZsh "https://github.com/ugase/dotfiles/blob/master/funcs.zsh"
    click TMUXConf "https://github.com/ugase/dotfiles/blob/master/.tmux/tmux.conf"
    click TMUXPlugins "https://github.com/ugase/dotfiles/tree/master/.tmux/plugins/"
    click AlacrittyToml "https://github.com/ugase/dotfiles/blob/master/.config/alacritty/alacritty.toml"
    click AlacrittyThemes "https://github.com/ugase/dotfiles/tree/master/.config/alacritty/themes/"
    click FootIni "https://github.com/ugase/dotfiles/blob/master/.config/foot/foot.ini"
    click NVIMInit "https://github.com/ugase/dotfiles/blob/master/.config/nvim/init.lua"
    click NVIMOptions "https://github.com/ugase/dotfiles/blob/master/.config/nvim/lua/options.lua"
    click NVIMMappings "https://github.com/ugase/dotfiles/blob/master/.config/nvim/lua/mappings.lua"
    click NVIMPlugins "https://github.com/ugase/dotfiles/tree/master/.config/nvim/lua/plugins/"
    click NVIMStyLua "https://github.com/ugase/dotfiles/blob/master/.config/nvim/stylua.toml"
    click SwayConfig "https://github.com/ugase/dotfiles/tree/master/.config/sway/config"
    click WaybarConfig "https://github.com/ugase/dotfiles/blob/master/.config/waybar/config.jsonc"
    click WaybarStyle "https://github.com/ugase/dotfiles/blob/master/.config/waybar/style.css"
    click OMPConfig "https://github.com/ugase/dotfiles/blob/master/.config/omp/config.toml"
    click FastfetchConfig "https://github.com/ugase/dotfiles/blob/master/.config/fastfetch/config.jsonc"
    click CronDot "https://github.com/ugase/dotfiles/blob/master/crontabs/dot.sh"
    click CronUpdate "https://github.com/ugase/dotfiles/blob/master/crontabs/update_index.sh"
    click Wallpapers "https://github.com/ugase/dotfiles/tree/master/Wallpapers/contents/"
    click Kanata "https://github.com/ugase/dotfiles/blob/master/kanata/kanta.kbd"
    click StowIgnore "https://github.com/ugase/dotfiles/blob/master/.stow-local-ignore"
```
