# nbbaier/dotfiles architecture

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

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

## Overview

1. This repository is a personal workstation dotfiles setup, not an application runtime. Its job is to bootstrap a macOS/dev environment by installing packages, wiring configs into the right locations, and customizing shells, editors, and OS behavior.

2. The top-level entry point is `install.sh`, which the README says to run after cloning with submodules. That implies the repo’s main flow is: clone → install dependencies/configs → create links or apply settings → use the machine normally.

3. The repo is organized by target boundary rather than by language:
   - `config/` holds app and tool configs that map to XDG-style config locations.
   - `apps/` holds app-specific overrides and plugin/snippet content.
   - `system/` holds shell-wide behavior shared across terminals and CLI tools.
   - `packages/` defines package-manager input files.
   - `macos/` contains machine-level defaults and integration scripts.
   - `bin/` contains custom helper commands used during setup and daily use.

4. `system/` is the core shell layer. It includes `zsh`-related initialization, aliases, completions, prompt setup, and plugin directories such as `fzf-tab`, autosuggestions, syntax highlighting, and autopairing. This is the main command-line UX layer that every shell session inherits.

5. `config/zsh/.zshrc` and `config/zsh/.zprofile`, plus the top-level `zshenv/.zshenv`, form the shell startup boundary. `zshenv` is likely for universal environment variables, while `zshrc`/`zprofile` handle interactive/login behavior and plugin loading.

6. `config/` is the broad application configuration area. It includes configs for terminal/UI and CLI tools such as `ghostty`, `aerospace`, `bat`, `fastfetch`, `gh`, `git`, `karabiner`, `micro`, `litecli`, `pandoc`, `twtxtr`, and `topgrade`. This is where most tool behavior is defined.

7. The editor/IDE layer is split across dedicated app folders:
   - `apps/vscode` with keybindings, settings, and snippets.
   - `apps/cursor` with Cursor settings.
   - `apps/smallweb` with plugin folders like `choose`, `edit`, `open`, and `status`.
   - `apps/tex/personal` with custom LaTeX class/style files.
   This suggests the repo treats editors and authoring tools as first-class, separately maintained subsystems.

8. `packages/` is the dependency declaration layer. Separate files exist for different ecosystems and installers: Brew, Bun, Code, Cursor, npm, Rust, and uv. That indicates package installation is centralized but segmented by package manager rather than managed in one monolith.

9. `macos/` contains OS-specific post-install customization. Files like `defaults.sh`, `dock.sh`, and `duti.sh` suggest this repo applies system preferences, Dock layout, and file-type associations after the base packages/configs are in place.

10. `bin/` is a utilities layer for repository automation and personal workflow commands. Names like `link_config`, `link_home`, `link_ides`, `install_extensions`, `is_installed`, and `dump_packages` indicate these scripts are used to connect repo content to the home directory and manage environment setup.

11. The repo also includes support files for individual CLI tools and workflows: `curl/.curlrc`, `jq/.jq`, and configs for `gh`, `bat`, `fastfetch`, `micro`, and `pandoc`. These are isolated so each tool can be updated independently without affecting the rest of the environment.

12. There are documentation files comparing dotfile management approaches (`dotfiles-with-chezmoi.md`, `dotfiles-with-stow.md`), which suggests the repo itself is a hand-rolled or custom-managed dotfiles system rather than being fully delegated to those tools.

13. Important architectural boundary: this repo does not appear to run a single service or build artifact. Its “output” is a configured machine state created by linking files, installing packages, and applying OS/editor/shell settings across many small, independent targets.

14. For an architecture diagram, the central nodes should be:
   - repository checkout,
   - bootstrap/install scripts,
   - package-manager manifests,
   - shell/system config,
   - app/editor configs,
   - macOS customization,
   - custom helper scripts.
   The main data flow is from version-controlled files into the user’s home directory, system preferences, and installed package state.

Main entry points: [`install.sh`](https://github.com/nbbaier/dotfiles/blob/main/install.sh) (install.sh), [`system/aliases`](https://github.com/nbbaier/dotfiles/tree/main/system/aliases) (System shell), [`config/bat/config`](https://github.com/nbbaier/dotfiles/tree/main/config/bat/config) (Tool configs), [`packages/brewfile`](https://github.com/nbbaier/dotfiles/tree/main/packages/brewfile) (Package manifests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_install_sh["install.sh<br/>bootstrap entry<br/>[install.sh]"]
end

subgraph group_shell["Shell layer"]
  node_system_zsh["System shell<br/>shell runtime"]
  node_zshenv["zshenv<br/>shell env<br/>[.zshenv]"]
  node_zshrc_profile["zsh rc/profile<br/>shell startup<br/>[.zshrc]"]
  node_shell_plugins["Shell plugins<br/>completion/plugins"]
  node_shell_prompt["Prompt setup<br/>shell prompt"]
end

subgraph group_config["Tool config"]
  node_config_git["Git config<br/>git settings"]
  node_config_ghostty["Terminal config<br/>terminal ui"]
  node_config_gh["GH config<br/>cli config<br/>[config.yml]"]
  node_config_misc["Tool configs<br/>tool settings"]
end

subgraph group_apps["App configs"]
  node_apps_vscode["VS Code<br/>editor config<br/>[settings.json]"]
  node_apps_cursor["Cursor<br/>editor config<br/>[settings.json]"]
  node_apps_smallweb["Smallweb<br/>plugin bundle"]
  node_apps_tex["LaTeX bundle<br/>authoring assets<br/>[baier.cls]"]
end

subgraph group_packages["Packages"]
  node_packages_manifests["Package manifests<br/>package inputs"]
end

subgraph group_macos["macOS"]
  node_macos_defaults["macOS defaults<br/>os tuning<br/>[defaults.sh]"]
  node_macos_duti["File associations<br/>os integration<br/>[duti.sh]"]
end

subgraph group_utilities["Utilities"]
  node_bin_linking["Link scripts<br/>setup helpers"]
  node_bin_install["Install tools<br/>setup helpers"]
  node_bin_admin["Repo utilities<br/>workflow helpers"]
end

node_install_sh -->|"installs"| node_packages_manifests
node_install_sh -->|"links"| node_bin_linking
node_install_sh -->|"configures"| node_bin_install
node_install_sh -->|"applies"| node_macos_defaults
node_install_sh -->|"sets"| node_macos_duti
node_install_sh -->|"enables"| node_system_zsh
node_bin_linking -->|"links"| node_zshenv
node_bin_linking -->|"links"| node_zshrc_profile
node_system_zsh -->|"loads"| node_shell_plugins
node_system_zsh -->|"loads"| node_shell_prompt
node_zshenv -->|"feeds"| node_zshrc_profile
node_system_zsh -->|"uses"| node_config_git
node_system_zsh -->|"uses"| node_config_gh
node_config_misc -->|"includes"| node_config_ghostty
node_config_misc -->|"includes"| node_config_git
node_config_misc -->|"includes"| node_config_gh
node_config_misc -.-> node_config_misc
node_apps_vscode -->|"supports"| node_apps_tex
node_apps_cursor -.->|"mirrors"| node_apps_vscode
node_apps_smallweb -.->|"used by"| node_bin_admin
node_packages_manifests -->|"drives"| node_bin_install
node_packages_manifests -->|"installs"| node_apps_vscode
node_packages_manifests -->|"installs"| node_apps_cursor
node_macos_defaults -.->|"pairs with"| node_macos_duti

click node_install_sh "https://github.com/nbbaier/dotfiles/blob/main/install.sh"
click node_bin_linking "https://github.com/nbbaier/dotfiles/tree/main/bin/link_config"
click node_bin_install "https://github.com/nbbaier/dotfiles/tree/main/bin/install_extensions"
click node_bin_admin "https://github.com/nbbaier/dotfiles/tree/main/bin/dump_packages"
click node_packages_manifests "https://github.com/nbbaier/dotfiles/tree/main/packages/brewfile"
click node_system_zsh "https://github.com/nbbaier/dotfiles/tree/main/system/aliases"
click node_zshenv "https://github.com/nbbaier/dotfiles/blob/main/zshenv/.zshenv"
click node_zshrc_profile "https://github.com/nbbaier/dotfiles/blob/main/config/zsh/.zshrc"
click node_shell_plugins "https://github.com/nbbaier/dotfiles/tree/main/system/plugins/fzf-tab"
click node_shell_prompt "https://github.com/nbbaier/dotfiles/tree/main/system/prompt/prompt_custom_setup"
click node_config_git "https://github.com/nbbaier/dotfiles/tree/main/config/git/config"
click node_config_ghostty "https://github.com/nbbaier/dotfiles/tree/main/config/ghostty/config"
click node_config_gh "https://github.com/nbbaier/dotfiles/blob/main/config/gh/config.yml"
click node_config_misc "https://github.com/nbbaier/dotfiles/tree/main/config/bat/config"
click node_apps_vscode "https://github.com/nbbaier/dotfiles/blob/main/apps/vscode/settings.json"
click node_apps_cursor "https://github.com/nbbaier/dotfiles/blob/main/apps/cursor/settings.json"
click node_apps_smallweb "https://github.com/nbbaier/dotfiles/tree/main/apps/smallweb/plugins/choose"
click node_apps_tex "https://github.com/nbbaier/dotfiles/blob/main/apps/tex/personal/baier.cls"
click node_macos_defaults "https://github.com/nbbaier/dotfiles/blob/main/macos/defaults.sh"
click node_macos_duti "https://github.com/nbbaier/dotfiles/blob/main/macos/duti.sh"

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_install_sh,node_bin_linking,node_bin_install,node_bin_admin toneBlue
class node_system_zsh,node_zshenv,node_zshrc_profile,node_shell_plugins,node_shell_prompt toneAmber
class node_config_git,node_config_ghostty,node_config_gh,node_config_misc toneMint
class node_apps_vscode,node_apps_cursor,node_apps_smallweb,node_apps_tex toneRose
class node_packages_manifests toneIndigo
class node_macos_defaults,node_macos_duti toneTeal
```

## Components

### Bootstrap

Entry points and repository-to-machine setup flow

- [install.sh](https://github.com/nbbaier/dotfiles/blob/main/install.sh): bootstrap entry · Top-level install flow for cloning, linking, and applying settings · `install.sh`

### Shell layer

Universal shell startup, aliases, completions, and prompt

- [System shell](https://github.com/nbbaier/dotfiles/tree/main/system/aliases): shell runtime · Shared aliases, completions, plugins, and prompt for every shell session · `system/aliases`
- [zshenv](https://github.com/nbbaier/dotfiles/blob/main/zshenv/.zshenv): shell env · Universal shell environment variables and startup setup · `zshenv/.zshenv`
- [zsh rc/profile](https://github.com/nbbaier/dotfiles/blob/main/config/zsh/.zshrc): shell startup · Interactive and login shell behavior and plugin loading · `config/zsh/.zshrc`
- [Shell plugins](https://github.com/nbbaier/dotfiles/tree/main/system/plugins/fzf-tab): completion/plugins · fzf-tab, autosuggestions, syntax highlighting, completions, and autopairing · `system/plugins/fzf-tab`
- [Prompt setup](https://github.com/nbbaier/dotfiles/tree/main/system/prompt/prompt_custom_setup): shell prompt · Custom prompt initialization and presentation · `system/prompt/prompt_custom_setup`

### Tool config

Shared application and CLI configuration files

- [Git config](https://github.com/nbbaier/dotfiles/tree/main/config/git/config): git settings · Core git configuration and ignore rules · `config/git/config`
- [Terminal config](https://github.com/nbbaier/dotfiles/tree/main/config/ghostty/config): terminal ui · Ghostty terminal settings · `config/ghostty/config`
- [GH config](https://github.com/nbbaier/dotfiles/blob/main/config/gh/config.yml): cli config · GitHub CLI configuration and host state · `config/gh/config.yml`
- [Tool configs](https://github.com/nbbaier/dotfiles/tree/main/config/bat/config): tool settings · Configs for bat, fastfetch, karabiner, micro, pandoc, litecli, twtxtr, topgrade, aerospace · `config/bat/config`

### App configs

Editor, authoring, and app-specific overrides

- [VS Code](https://github.com/nbbaier/dotfiles/blob/main/apps/vscode/settings.json): editor config · Keybindings, settings, and snippets for VS Code · `apps/vscode/settings.json`
- [Cursor](https://github.com/nbbaier/dotfiles/blob/main/apps/cursor/settings.json): editor config · Cursor settings and editor-specific overrides · `apps/cursor/settings.json`
- [Smallweb](https://github.com/nbbaier/dotfiles/tree/main/apps/smallweb/plugins/choose): plugin bundle · Smallweb plugin commands and extensions · `apps/smallweb/plugins/choose`
- [LaTeX bundle](https://github.com/nbbaier/dotfiles/blob/main/apps/tex/personal/baier.cls): authoring assets · Personal class and style files for TeX authoring · `apps/tex/personal/baier.cls`

### Packages

Package-manager manifests for installing dependencies

- [Package manifests](https://github.com/nbbaier/dotfiles/tree/main/packages/brewfile): package inputs · Brew, Bun, Code, Cursor, npm, Rust, and uv manifests · `packages/brewfile`

### macOS

Machine-specific defaults and integrations

- [macOS defaults](https://github.com/nbbaier/dotfiles/blob/main/macos/defaults.sh): os tuning · System preference and Dock customization scripts · `macos/defaults.sh`
- [File associations](https://github.com/nbbaier/dotfiles/blob/main/macos/duti.sh): os integration · Default app and file-type association setup · `macos/duti.sh`

### Utilities

Helper scripts used by setup and daily workflow

- [Link scripts](https://github.com/nbbaier/dotfiles/tree/main/bin/link_config): setup helpers · Repository scripts that connect files into the home/config locations · `bin/link_config`
- [Install tools](https://github.com/nbbaier/dotfiles/tree/main/bin/install_extensions): setup helpers · Scripts for installing extensions and checking local dependencies · `bin/install_extensions`
- [Repo utilities](https://github.com/nbbaier/dotfiles/tree/main/bin/dump_packages): workflow helpers · Miscellaneous automation for package dumping, remotes, and symlinks · `bin/dump_packages`

## Connections

- install.sh → Package manifests: installs · Reads package manifests and installs dependencies
- install.sh → Link scripts: links · Uses helper scripts to place repo files into target locations
- install.sh → Install tools: configures · Runs extension and dependency installation helpers
- install.sh → macOS defaults: applies · Runs machine-specific defaults after base setup
- install.sh → File associations: sets · Applies default application associations
- install.sh → System shell: enables · Wires shell-wide behavior into the user environment
- Link scripts → zshenv: links · Installs universal shell environment file
- Link scripts → zsh rc/profile: links · Installs login/interactive shell startup files
- System shell → Shell plugins: loads · Provides plugin directories and completions
- System shell → Prompt setup: loads · Configures the custom shell prompt
- zshenv → zsh rc/profile: feeds · Provides environment used by interactive and login shells
- System shell → Git config: uses · Shares CLI defaults that support shell workflows
- System shell → GH config: uses · Integrates GitHub CLI behavior into the shell environment
- Tool configs → Terminal config: includes · Tool-specific configuration set under config/
- Tool configs → Git config: includes · Tool-specific configuration set under config/
- Tool configs → GH config: includes · Tool-specific configuration set under config/
- Tool configs → Tool configs: Representative shared config boundary for multiple tools
- VS Code → LaTeX bundle: supports · Editor snippets and authoring assets support text/LaTeX workflows
- Cursor → VS Code: mirrors · Separate editor config with similar personal preferences
- Smallweb → Repo utilities: used by · App plugin workflow relies on local helper scripts and automation
- Package manifests → Install tools: drives · Package declarations are consumed by install helpers
- Package manifests → VS Code: installs · Includes editor-related package manifests and extensions
- Package manifests → Cursor: installs · Includes Cursor-related package manifests
- macOS defaults → File associations: pairs with · System preference changes and app associations form the OS layer
