# mdrmono/dotfiles architecture

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

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

## Overview

1. This repository is a personal dotfiles monorepo, not an application service. Its core architecture is a set of user-scoped configuration packages that are deployed into `~` and `~/.config` through GNU Stow-created symlinks.

2. The main boundary is “source of truth in git” vs. “live config in the home directory.” After `stow .`, each package under `.config/` maps to the corresponding runtime config location, so desktop tools and editors read their settings directly from symlinked files at startup.

3. The desktop/session layer is centered on `i3`, `polybar`, and `rofi`. `i3/config` defines the window manager behavior, `polybar/config.ini` defines the status bar, and `rofi/config.rasi` controls the app launcher. These components form the interactive shell of the Linux desktop.

4. `scripts/util/` contains operational glue for the desktop environment. The scripts for battery alerts, Bluetooth control/status, dual-monitor setup, Polybar launch, and Toggl tracking are likely invoked from `i3` keybindings, bar actions, or startup hooks. This is the repo’s main automation layer.

5. Terminal and shell customization are split between `.config/alacritty/` and `.p10k.zsh`. Alacritty handles terminal appearance and behavior, while Powerlevel10k configures the Zsh prompt. These are user-facing presentation layers rather than app logic.

6. The editor subsystem has two parallel stacks: VS Code under `.config/Code/User/` and Neovim under `.config/nvim/`. Neovim uses a LazyVim-style Lua layout (`init.lua`, `lua/config/*`, `lua/plugins/*`, `lazy-lock.json`), while VS Code is configured through JSON settings/keybindings. Doom Emacs is a third editor configuration path under `.config/doom/` with the usual `init.el`, `config.el`, and `packages.el`.

7. Input method and locale-related behavior live under `.config/fcitx5/`. Those files control the IME profile and text input behavior, which makes this a system integration boundary rather than an app-specific config.

8. `calibre` is mostly a user-state and customization subtree rather than pure static config. It includes conversion settings, viewer/webengine settings, plugins, fonts caches, server config, and a large set of annotation files. This indicates the repo also preserves runtime preferences and content-processing state for Calibre.

9. The repo includes application-specific defaults and caches only where they matter to user experience: `calibre` state, `alacritty` themes, and editor metadata such as `.config/nvim/lazy-lock.json` and `.config/nvim/.neoconf.json`. These files capture versioned behavior and plugin pinning, which affects reproducibility.

10. `.env.example` is the only explicit environment handoff file at the root. It signals that some scripts or configs depend on local machine secrets or account-specific variables, but those values are intentionally kept outside version control.

11. Overall data flow is straightforward: git-managed dotfiles -> Stow symlinks -> desktop apps/editors/shell load configs at launch -> helper scripts are called by the session. There are no long-running services, databases, or backend APIs; the architecture is entirely user-session and workstation configuration.

Main entry points: [`.config/nvim/init.lua`](https://github.com/mdrmono/dotfiles/blob/main/.config/nvim/init.lua) (Init), [`.config/i3/config`](https://github.com/mdrmono/dotfiles/blob/main/.config/i3/config) (i3 config), [`.config/polybar/config.ini`](https://github.com/mdrmono/dotfiles/blob/main/.config/polybar/config.ini) (Polybar), [`.config/nvim`](https://github.com/mdrmono/dotfiles/blob/main/.config/nvim) (Neovim)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_git["Git source"]
  node_root["dotfiles"]
  node_env[".env.example<br/>env template<br/>[.env.example]"]
end

subgraph group_deploy["Deployment"]
  node_stow["GNU Stow<br/>deploy tool"]
  node_home[("Live config<br/>home tree")]
end

subgraph group_desktop["Desktop shell"]
  node_i3["i3 config<br/>wm config<br/>[config]"]
  node_polybar["Polybar<br/>status bar<br/>[config.ini]"]
  node_rofi["Rofi<br/>launcher config<br/>[config.rasi]"]
end

subgraph group_editors["Editors"]
  node_nvim["Neovim<br/>editor stack<br/>[nvim]"]
  node_nvim_init["Init<br/>nvim entry<br/>[init.lua]"]
  node_nvim_cfg["Lua config<br/>nvim config<br/>[config]"]
  node_nvim_plugins["Plugins<br/>[plugins]"]
  node_vscode["VS Code<br/>editor config<br/>[User]"]
  node_doom["Doom Emacs<br/>editor config<br/>[doom]"]
end

subgraph group_terminal["Terminal shell"]
  node_alacritty["Alacritty<br/>terminal config<br/>[alacritty.toml]"]
  node_p10k["Powerlevel10k<br/>zsh prompt<br/>[.p10k.zsh]"]
end

subgraph group_system["System input"]
  node_fcitx5["Fcitx5<br/>ime config<br/>[fcitx5]"]
end

subgraph group_apps["App state"]
  node_calibre["Calibre<br/>app state<br/>[calibre]"]
end

subgraph group_automation["Automation"]
  node_desktop_scripts["Session scripts<br/>shell automation"]
end

node_root -->|"deploys via"| node_stow
node_stow -->|"materializes"| node_home
node_home -->|"loads"| node_i3
node_home -->|"loads"| node_polybar
node_home -->|"loads"| node_rofi
node_home -->|"loads"| node_alacritty
node_home -->|"loads"| node_p10k
node_home -->|"loads"| node_nvim
node_nvim -->|"boots"| node_nvim_init
node_nvim_init -->|"delegates to"| node_nvim_cfg
node_nvim_init -->|"loads"| node_nvim_plugins
node_home -->|"loads"| node_vscode
node_home -->|"loads"| node_doom
node_home -->|"loads"| node_fcitx5
node_home -->|"persists"| node_calibre
node_i3 -.->|"invokes"| node_desktop_scripts
node_polybar -.->|"invokes"| node_desktop_scripts
node_root -->|"documents"| node_env

click node_i3 "https://github.com/mdrmono/dotfiles/blob/main/.config/i3/config"
click node_polybar "https://github.com/mdrmono/dotfiles/blob/main/.config/polybar/config.ini"
click node_rofi "https://github.com/mdrmono/dotfiles/blob/main/.config/rofi/config.rasi"
click node_desktop_scripts "https://github.com/mdrmono/dotfiles/tree/main/scripts/util"
click node_alacritty "https://github.com/mdrmono/dotfiles/blob/main/.config/alacritty/alacritty.toml"
click node_p10k "https://github.com/mdrmono/dotfiles/blob/main/.p10k.zsh"
click node_nvim "https://github.com/mdrmono/dotfiles/blob/main/.config/nvim"
click node_nvim_init "https://github.com/mdrmono/dotfiles/blob/main/.config/nvim/init.lua"
click node_nvim_cfg "https://github.com/mdrmono/dotfiles/blob/main/.config/nvim/lua/config"
click node_nvim_plugins "https://github.com/mdrmono/dotfiles/blob/main/.config/nvim/lua/plugins"
click node_vscode "https://github.com/mdrmono/dotfiles/blob/main/.config/Code/User"
click node_doom "https://github.com/mdrmono/dotfiles/blob/main/.config/doom"
click node_fcitx5 "https://github.com/mdrmono/dotfiles/blob/main/.config/fcitx5"
click node_calibre "https://github.com/mdrmono/dotfiles/blob/main/.config/calibre"
click node_env "https://github.com/mdrmono/dotfiles/blob/main/.env.example"

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_root,node_env,node_calibre toneBlue
class node_stow,node_home,node_desktop_scripts toneAmber
class node_i3,node_polybar,node_rofi toneMint
class node_nvim,node_nvim_init,node_nvim_cfg,node_nvim_plugins,node_vscode,node_doom toneRose
class node_alacritty,node_p10k toneIndigo
class node_fcitx5 toneTeal
```

## Components

### Git source

Versioned dotfiles and repo-managed state.

- **dotfiles**: repo · Personal workstation configuration monorepo.
- [.env.example](https://github.com/mdrmono/dotfiles/blob/main/.env.example): env template · Template for local secrets and machine-specific variables. · `.env.example`

### Deployment

How tracked files become live home-directory config.

- **GNU Stow**: deploy tool · Creates symlinks from repo packages into the home directory.
- **Live config**: home tree · Actual runtime files read from ~/.config and ~.

### Desktop shell

Window manager, bar, launcher, and session glue.

- [i3 config](https://github.com/mdrmono/dotfiles/blob/main/.config/i3/config): wm config · Window manager behavior and keybindings. · `.config/i3/config`
- [Polybar](https://github.com/mdrmono/dotfiles/blob/main/.config/polybar/config.ini): status bar · Desktop status bar configuration. · `.config/polybar/config.ini`
- [Rofi](https://github.com/mdrmono/dotfiles/blob/main/.config/rofi/config.rasi): launcher config · Application launcher appearance and behavior. · `.config/rofi/config.rasi`

### Editors

Editor configurations and plugin pinning.

- [Neovim](https://github.com/mdrmono/dotfiles/blob/main/.config/nvim): editor stack · LazyVim-style Lua editor configuration. · `.config/nvim`
- [Init](https://github.com/mdrmono/dotfiles/blob/main/.config/nvim/init.lua): nvim entry · Bootstraps Neovim and plugin loading. · `.config/nvim/init.lua`
- [Lua config](https://github.com/mdrmono/dotfiles/blob/main/.config/nvim/lua/config): nvim config · Options, keymaps, autocmds, and lazy setup. · `.config/nvim/lua/config`
- [Plugins](https://github.com/mdrmono/dotfiles/blob/main/.config/nvim/lua/plugins): nvim plugins · Plugin declarations and highlighting extensions. · `.config/nvim/lua/plugins`
- [VS Code](https://github.com/mdrmono/dotfiles/blob/main/.config/Code/User): editor config · User settings and keybindings for VS Code. · `.config/Code/User`
- [Doom Emacs](https://github.com/mdrmono/dotfiles/blob/main/.config/doom): editor config · Doom Emacs init, config, and package declarations. · `.config/doom`

### Terminal shell

Terminal emulator and Zsh prompt customization.

- [Alacritty](https://github.com/mdrmono/dotfiles/blob/main/.config/alacritty/alacritty.toml): terminal config · Terminal appearance and runtime behavior. · `.config/alacritty/alacritty.toml`
- [Powerlevel10k](https://github.com/mdrmono/dotfiles/blob/main/.p10k.zsh): zsh prompt · Shell prompt customization in Zsh. · `.p10k.zsh`

### System input

IME and workstation integration settings.

- [Fcitx5](https://github.com/mdrmono/dotfiles/blob/main/.config/fcitx5): ime config · Input method profile and text input behavior. · `.config/fcitx5`

### App state

User preferences and runtime state preserved for apps.

- [Calibre](https://github.com/mdrmono/dotfiles/blob/main/.config/calibre): app state · Preferences, plugins, viewer annotations, and conversion settings. · `.config/calibre`

### Automation

Session scripts invoked by desktop hooks and bindings.

- [Session scripts](https://github.com/mdrmono/dotfiles/tree/main/scripts/util): shell automation · Battery, Bluetooth, monitor, Polybar, and Toggl helpers. · `scripts/util`

## Connections

- dotfiles → GNU Stow: deploys via · Repository packages are installed into the home tree with symlinks.
- GNU Stow → Live config: materializes · Stow exposes tracked files as live config under ~ and ~/.config.
- Live config → i3 config: loads · i3 reads its config at session start.
- Live config → Polybar: loads · Polybar consumes its INI config when launched.
- Live config → Rofi: loads · Rofi reads launcher styling and behavior from the symlinked file.
- Live config → Alacritty: loads · Alacritty reads terminal settings from the live config path.
- Live config → Powerlevel10k: loads · Zsh loads the prompt theme from the home directory.
- Live config → Neovim: loads · Neovim starts from the symlinked editor tree.
- Neovim → Init: boots · Entry point for plugin initialization.
- Init → Lua config: delegates to · Core editor behavior is split into config modules.
- Init → Plugins: loads · Plugin specifications are loaded during startup.
- Live config → VS Code: loads · VS Code reads user settings and keybindings.
- Live config → Doom Emacs: loads · Doom Emacs uses the tracked init/config/package files.
- Live config → Fcitx5: loads · IME profile and input behavior are consumed by the desktop session.
- Live config → Calibre: persists · Calibre preferences and state are kept as user-scoped application data.
- i3 config → Session scripts: invokes · Keybindings and hooks likely call session helper scripts.
- Polybar → Session scripts: invokes · Bar actions and startup hooks use utility scripts.
- dotfiles → .env.example: documents · Template for required local environment variables.
