# ppcamp/dotfiles architecture

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

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

## Overview

1. **Repo purpose and runtime**
   This is a ChezMoi-managed dotfiles repository, not an application. The main “runtime” is ChezMoi itself: it renders templates, materializes files into the user’s home directory, and triggers scripts when tracked inputs change.

2. **Primary orchestration layer**
   The root ChezMoi files define how the repo is applied:
   - `.chezmoi.yaml.tmpl`, `.chezmoidata.yaml`, `.chezmoiignore`
   - `.chezmoiscripts/` for lifecycle hooks
   - `.chezmoitemplates/` for shared template fragments  
   These form the control plane that decides what gets installed, when, and with which host-specific values.

3. **Declarative vs imperative boundary**
   The repo has a clear split between:
   - declarative managed dotfiles and templates
   - imperative `run_onchange_*` scripts that perform installation/setup work  
   That boundary is important: ChezMoi manages file state, while scripts handle provisioning, package installs, and system setup.

4. **Package/tool bootstrap subsystem**
   The large set of `.chezmoiscripts/run_onchange_install-*.tmpl` files is the provisioning engine for local tooling. It covers package managers and utilities such as:
   - `asdf`, `homebrew`, `brew-like` tooling
   - CLI tools (`fzf`, `rg`, `yq`, `zoxide`, `lazygit`, `gh`, `bat`, `eza`, `podman`, `nvim`, etc.)
   - optional sudo-backed installs for system-wide tools  
   This suggests a “tooling platform” architecture rather than a single-language project.

5. **Shell environment subsystem**
   `dot_local/share/shell/` is a self-contained Zsh environment with:
   - internal config loading
   - plugins
   - snippets
   - completion definitions  
   It is paired with shell entry files such as `dot_zshenv.tmpl` and `dot_local/share/shell/init.zsh.tmpl`. The shell layer is the user’s command-line base, with plugin-style composition for aliases, completions, SSH agent handling, `fzf`, `zoxide`, `tldr`, and prompt/utility behavior.

6. **Editor/IDE subsystem: Neovim**
   `dot_config/nvim/` is a full Neovim distribution layered on LazyVim-style plugin management. It includes:
   - core config and keymaps in `lua/config/`
   - custom commands in `lua/commands/`
   - reusable utilities in `lua/utils/`
   - plugin modules in `lua/plugins/`
   - LSP server configs in `lsp/`  
   This is a major subsystem with its own internal architecture, distinct from the shell config.

7. **Neovim integration boundaries**
   The Neovim config is split by capability:
   - editor behavior, UI, and startup
   - language tooling via LSP, completion, formatting, linting, debugging
   - UI plugins for buffers, statusline, notifications, file explorer, start page, etc.
   - AI-assisted editing via `lua/plugins/ai.lua`  
   This makes Neovim both an editor and an IDE shell around external language servers and developer tools.

8. **AI assistant / agent tooling**
   `dot_claude/` and `dot_openclaude/` define local AI assistant workflows:
   - agent definitions
   - commands
   - skills
   - memory/state directories
   - settings files  
   This is a separate operational boundary from the editor and shell: it provides prompt/agent behavior, workflows like review/help/refactor, and local persistent context.

9. **Host and platform-specific integrations**
   Several files target OS/runtime integration rather than general config:
   - `dot_config/distrobox-home/` and `tools/Containerfile` for containerized Linux user environments
   - `dot_ssh/allowed_signers.tmpl` for SSH trust configuration
   - `dot_git-template`, `dot_gitconfig.tmpl`, `dot_golangci.yml`, `dot_lefthook.yaml`
   - `dot_config/kitty/`, `dot_config/lazygit/`, `dot_config/starship.toml`  
   These are the “adjacent systems” around the shell/editor core.

10. **Provisioning helpers and custom scripts**
   The `tools/` directory contains standalone utility scripts (`gitx`, `now`, `perm`, `screenreader`, `xcp`, `xpb`) plus a container profile JSON. These are likely installed or symlinked into the user’s PATH and complement the shell plugins and completions.

11. **Shared assets and generated files**
   `dot_local/share/fonts/` and shell completion files under `dot_local/share/shell/completions/` are asset-like managed content. They are not logic-heavy, but they matter in the architecture because they are the distribution mechanism for CLI ergonomics and terminal/UI consistency.

12. **Documentation as part of the configuration system**
   `docs/` is substantial and documents operational choices for ASDF, Kitty, Neovim, Git, GRUB, zsh, package inspection, and program recommendations. In practice, this repo is a documented operating environment, not just a file dump.

13. **Overall data flow**
   The main flow is: repository state + host data + templates → ChezMoi renders files → files land in home/config paths → shell/editor/assistant tooling consumes them → `run_onchange` scripts provision missing packages or system setup when inputs change. That is the key architecture diagram to draw.

Main entry points: [`.chezmoi.yaml.tmpl`](https://github.com/ppcamp/dotfiles/blob/main/.chezmoi.yaml.tmpl) (ChezMoi root), [`dot_local/share/shell/internal/configs/configs.zsh`](https://github.com/ppcamp/dotfiles/blob/main/dot_local/share/shell/internal/configs/configs.zsh) (Shell core), [`.chezmoiscripts/run_onchange_install-asdf.tmpl`](https://github.com/ppcamp/dotfiles/blob/main/.chezmoiscripts/run_onchange_install-asdf.tmpl) (Tool installers), [`.chezmoiscripts`](https://github.com/ppcamp/dotfiles/blob/main/.chezmoiscripts) (Lifecycle scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_control["Control plane"]
  node_n_chezmoi_root["ChezMoi root<br/>chezmoi config<br/>[.chezmoi.yaml.tmpl]"]
  node_n_chezmoidata["Host data<br/>chezmoi data<br/>[.chezmoidata.yaml]"]
  node_n_chezmoiignore["Ignore rules<br/>chezmoi filter<br/>[.chezmoiignore]"]
  node_n_templates["Shared templates<br/>template partials<br/>[.chezmoitemplates]"]
end

subgraph group_grp_bootstrap["Bootstrap"]
  node_n_scripts["Lifecycle scripts<br/>run_onchange hooks<br/>[.chezmoiscripts]"]
  node_n_installers["Tool installers<br/>provisioning scripts"]
end

subgraph group_grp_shell["Shell"]
  node_n_shell_entry["Shell entry<br/>zsh bootstrap<br/>[dot_zshenv.tmpl]"]
  node_n_shell_core["Shell core<br/>zsh framework<br/>[configs.zsh]"]
  node_n_shell_plugins["Shell plugins<br/>zsh plugins"]
  node_n_shell_snippets["Shell snippets<br/>zsh snippets"]
  node_n_shell_completions["Completions"]
end

subgraph group_grp_editor["Neovim"]
  node_n_nvim_init["Neovim entry<br/>editor bootstrap<br/>[init.lua]"]
  node_n_nvim_config["Core config<br/>nvim config"]
  node_n_nvim_plugins["Plugin stack<br/>nvim plugins"]
  node_n_nvim_lsp["LSP configs<br/>language servers"]
end

subgraph group_grp_ai["AI assistants"]
  node_n_claude["Claude setup<br/>assistant config"]
  node_n_openclaude["OpenClaude<br/>assistant workflows"]
end

subgraph group_grp_system["System integrations"]
  node_n_kitty["Kitty config<br/>terminal config"]
  node_n_starship["Prompt<br/>[starship.toml]"]
  node_n_git["Git setup<br/>git config<br/>[dot_gitconfig.tmpl]"]
end

subgraph group_grp_tools["Tools"]
  node_n_tools["Tool scripts<br/>local utilities"]
  node_n_container["Container tools<br/>container assets"]
end

subgraph group_grp_docs["Docs"]
  node_n_docs["Docs<br/>documentation"]
end

node_n_chezmoi_root -->|"uses"| node_n_chezmoidata
node_n_chezmoi_root -->|"filters"| node_n_chezmoiignore
node_n_chezmoi_root -->|"renders with"| node_n_templates
node_n_chezmoi_root -->|"drives"| node_n_scripts
node_n_scripts -->|"installs"| node_n_installers
node_n_scripts -->|"sets up"| node_n_container
node_n_chezmoi_root -->|"materializes"| node_n_shell_entry
node_n_shell_entry -->|"loads"| node_n_shell_core
node_n_shell_core -->|"composes"| node_n_shell_plugins
node_n_shell_core -->|"sources"| node_n_shell_snippets
node_n_shell_core -->|"enables"| node_n_shell_completions
node_n_chezmoi_root -->|"materializes"| node_n_nvim_init
node_n_nvim_init -->|"boots"| node_n_nvim_config
node_n_nvim_init -->|"loads"| node_n_nvim_plugins
node_n_nvim_plugins -->|"integrates"| node_n_nvim_lsp
node_n_chezmoi_root -->|"materializes"| node_n_claude
node_n_chezmoi_root -->|"materializes"| node_n_openclaude
node_n_chezmoi_root -->|"materializes"| node_n_kitty
node_n_chezmoi_root -->|"materializes"| node_n_starship
node_n_chezmoi_root -->|"materializes"| node_n_git
node_n_chezmoi_root -->|"deploys"| node_n_tools
node_n_chezmoi_root -.->|"documents"| node_n_docs
node_n_installers -.->|"supports"| node_n_shell_plugins
node_n_installers -.->|"supports"| node_n_nvim_plugins
node_n_installers -.->|"supports"| node_n_claude
node_n_tools -.->|"used by"| node_n_shell_core
node_n_container -.->|"isolates"| node_n_shell_entry

click node_n_chezmoi_root "https://github.com/ppcamp/dotfiles/blob/main/.chezmoi.yaml.tmpl"
click node_n_chezmoidata "https://github.com/ppcamp/dotfiles/blob/main/.chezmoidata.yaml"
click node_n_chezmoiignore "https://github.com/ppcamp/dotfiles/blob/main/.chezmoiignore"
click node_n_templates "https://github.com/ppcamp/dotfiles/blob/main/.chezmoitemplates"
click node_n_scripts "https://github.com/ppcamp/dotfiles/blob/main/.chezmoiscripts"
click node_n_installers "https://github.com/ppcamp/dotfiles/blob/main/.chezmoiscripts/run_onchange_install-asdf.tmpl"
click node_n_shell_entry "https://github.com/ppcamp/dotfiles/blob/main/dot_zshenv.tmpl"
click node_n_shell_core "https://github.com/ppcamp/dotfiles/blob/main/dot_local/share/shell/internal/configs/configs.zsh"
click node_n_shell_plugins "https://github.com/ppcamp/dotfiles/tree/main/dot_local/share/shell/plugins"
click node_n_shell_snippets "https://github.com/ppcamp/dotfiles/tree/main/dot_local/share/shell/snippets"
click node_n_shell_completions "https://github.com/ppcamp/dotfiles/tree/main/dot_local/share/shell/completions"
click node_n_nvim_init "https://github.com/ppcamp/dotfiles/blob/main/dot_config/nvim/init.lua"
click node_n_nvim_config "https://github.com/ppcamp/dotfiles/tree/main/dot_config/nvim/lua/config"
click node_n_nvim_plugins "https://github.com/ppcamp/dotfiles/tree/main/dot_config/nvim/lua/plugins"
click node_n_nvim_lsp "https://github.com/ppcamp/dotfiles/tree/main/dot_config/nvim/lsp"
click node_n_claude "https://github.com/ppcamp/dotfiles/tree/main/dot_claude"
click node_n_openclaude "https://github.com/ppcamp/dotfiles/tree/main/dot_openclaude"
click node_n_kitty "https://github.com/ppcamp/dotfiles/tree/main/dot_config/kitty"
click node_n_starship "https://github.com/ppcamp/dotfiles/blob/main/dot_config/starship.toml"
click node_n_git "https://github.com/ppcamp/dotfiles/blob/main/dot_gitconfig.tmpl"
click node_n_tools "https://github.com/ppcamp/dotfiles/tree/main/tools/scripts"
click node_n_container "https://github.com/ppcamp/dotfiles/tree/main/tools/Containerfile"
click node_n_docs "https://github.com/ppcamp/dotfiles/tree/main/docs"

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_n_chezmoi_root,node_n_chezmoidata,node_n_chezmoiignore,node_n_templates,node_n_tools,node_n_container toneBlue
class node_n_scripts,node_n_installers,node_n_docs toneAmber
class node_n_shell_entry,node_n_shell_core,node_n_shell_plugins,node_n_shell_snippets,node_n_shell_completions toneMint
class node_n_nvim_init,node_n_nvim_config,node_n_nvim_plugins,node_n_nvim_lsp toneRose
class node_n_claude,node_n_openclaude toneIndigo
class node_n_kitty,node_n_starship,node_n_git toneTeal
```

## Components

### Control plane

ChezMoi entrypoints, shared templates, and lifecycle hooks.

- [ChezMoi root](https://github.com/ppcamp/dotfiles/blob/main/.chezmoi.yaml.tmpl): chezmoi config · Top-level templates and managed-state rules that drive the repo. · `.chezmoi.yaml.tmpl`
- [Host data](https://github.com/ppcamp/dotfiles/blob/main/.chezmoidata.yaml): chezmoi data · Host- and machine-specific values used during rendering. · `.chezmoidata.yaml`
- [Ignore rules](https://github.com/ppcamp/dotfiles/blob/main/.chezmoiignore): chezmoi filter · Files excluded from management or rendering. · `.chezmoiignore`
- [Shared templates](https://github.com/ppcamp/dotfiles/blob/main/.chezmoitemplates): template partials · Reusable template fragments for installs and common logic. · `.chezmoitemplates`

### Bootstrap

Imperative provisioning and install scripts driven by ChezMoi.

- [Lifecycle scripts](https://github.com/ppcamp/dotfiles/blob/main/.chezmoiscripts): run_onchange hooks · Imperative hooks that provision tools and react to changes. · `.chezmoiscripts`
- [Tool installers](https://github.com/ppcamp/dotfiles/blob/main/.chezmoiscripts/run_onchange_install-asdf.tmpl): provisioning scripts · Install and setup scripts for CLI tools, system packages, and optional sudo-backed installs. · `.chezmoiscripts/run_onchange_install-asdf.tmpl`

### Shell

Zsh environment, plugins, snippets, and completions.

- [Shell entry](https://github.com/ppcamp/dotfiles/blob/main/dot_zshenv.tmpl): zsh bootstrap · Entry files that assemble the interactive shell environment. · `dot_zshenv.tmpl`
- [Shell core](https://github.com/ppcamp/dotfiles/blob/main/dot_local/share/shell/internal/configs/configs.zsh): zsh framework · Shared configs, loaders, paths, variables, and plugin wiring. · `dot_local/share/shell/internal/configs/configs.zsh`
- [Shell plugins](https://github.com/ppcamp/dotfiles/tree/main/dot_local/share/shell/plugins): zsh plugins · Composable shell features such as aliases, env cache, fzf, gh, pet, ssh-agent, tldr, and zoxide. · `dot_local/share/shell/plugins`
- [Shell snippets](https://github.com/ppcamp/dotfiles/tree/main/dot_local/share/shell/snippets): zsh snippets · Small reusable shell functions and aliases. · `dot_local/share/shell/snippets`
- [Completions](https://github.com/ppcamp/dotfiles/tree/main/dot_local/share/shell/completions): shell completions · Generated and managed command completion definitions. · `dot_local/share/shell/completions`

### Neovim

Full editor/IDE configuration and language tooling.

- [Neovim entry](https://github.com/ppcamp/dotfiles/blob/main/dot_config/nvim/init.lua): editor bootstrap · Main Neovim entrypoint and startup wiring. · `dot_config/nvim/init.lua`
- [Core config](https://github.com/ppcamp/dotfiles/tree/main/dot_config/nvim/lua/config): nvim config · Options, keymaps, lazy loader state, and core behavior. · `dot_config/nvim/lua/config`
- [Plugin stack](https://github.com/ppcamp/dotfiles/tree/main/dot_config/nvim/lua/plugins): nvim plugins · Editor, IDE, UI, AI, and workflow plugin modules. · `dot_config/nvim/lua/plugins`
- [LSP configs](https://github.com/ppcamp/dotfiles/tree/main/dot_config/nvim/lsp): language servers · Per-server configuration for language tooling integration. · `dot_config/nvim/lsp`

### AI assistants

Local assistant workflows, agents, skills, and memory.

- [Claude setup](https://github.com/ppcamp/dotfiles/tree/main/dot_claude): assistant config · Claude-related settings, commands, agents, skills, and memory. · `dot_claude`
- [OpenClaude](https://github.com/ppcamp/dotfiles/tree/main/dot_openclaude): assistant workflows · Alternative assistant workflows, agents, rules, and skills. · `dot_openclaude`

### System integrations

Host, terminal, and platform-specific configuration.

- [Kitty config](https://github.com/ppcamp/dotfiles/tree/main/dot_config/kitty): terminal config · Terminal emulator settings and helper scripts. · `dot_config/kitty`
- [Prompt](https://github.com/ppcamp/dotfiles/blob/main/dot_config/starship.toml): shell prompt · Cross-shell prompt configuration. · `dot_config/starship.toml`
- [Git setup](https://github.com/ppcamp/dotfiles/blob/main/dot_gitconfig.tmpl): git config · Git defaults, templates, hooks, and trust-related settings. · `dot_gitconfig.tmpl`

### Tools

Standalone helper scripts and container assets.

- [Tool scripts](https://github.com/ppcamp/dotfiles/tree/main/tools/scripts): local utilities · Standalone helper commands exposed through the user PATH. · `tools/scripts`
- [Container tools](https://github.com/ppcamp/dotfiles/tree/main/tools/Containerfile): container assets · Containerfile and profile assets for isolated Linux environments. · `tools/Containerfile`

### Docs

Repository documentation and operational guidance.

- [Docs](https://github.com/ppcamp/dotfiles/tree/main/docs): documentation · Operational guidance and setup notes for the environment. · `docs`

## Connections

- ChezMoi root → Host data: uses · Rendering combines repo defaults with host data.
- ChezMoi root → Ignore rules: filters · Exclude paths from management.
- ChezMoi root → Shared templates: renders with · Templates provide shared logic for managed files and scripts.
- ChezMoi root → Lifecycle scripts: drives · ChezMoi lifecycle hooks coordinate provisioning.
- Lifecycle scripts → Tool installers: installs · Install hooks provision packages and tools.
- Lifecycle scripts → Container tools: sets up · Some hooks build container-based environments.
- ChezMoi root → Shell entry: materializes · Managed shell entry files land in the home directory.
- Shell entry → Shell core: loads · Entry scripts source core shell configuration.
- Shell core → Shell plugins: composes · Core shell behavior is extended by plugins.
- Shell core → Shell snippets: sources · Reusable snippets extend interactive shell behavior.
- Shell core → Completions: enables · Completion definitions are wired into the shell.
- ChezMoi root → Neovim entry: materializes · Neovim distribution is installed as managed config.
- Neovim entry → Core config: boots · Startup loads core options, keymaps, and state.
- Neovim entry → Plugin stack: loads · Plugin modules define the editor and IDE stack.
- Plugin stack → LSP configs: integrates · Plugins connect Neovim to language servers.
- ChezMoi root → Claude setup: materializes · Claude assistant configuration is managed by ChezMoi.
- ChezMoi root → OpenClaude: materializes · OpenClaude workflows are managed separately from editor config.
- ChezMoi root → Kitty config: materializes · Terminal configuration is deployed as user config.
- ChezMoi root → Prompt: materializes · Prompt configuration is rendered into the environment.
- ChezMoi root → Git setup: materializes · Git configuration and templates are managed files.
- ChezMoi root → Tool scripts: deploys · Helper commands are made available in PATH.
- ChezMoi root → Docs: documents · Docs describe the operating environment and setup choices.
- Tool installers → Shell plugins: supports · Installed tools back shell plugins and completions.
- Tool installers → Plugin stack: supports · Tooling installs satisfy editor plugins and IDE features.
- Tool installers → Claude setup: supports · AI assistant workflows depend on local tools and models.
- Tool scripts → Shell core: used by · Utilities are exposed through shell functions and shortcuts.
- Container tools → Shell entry: isolates · Container environments reuse the shell configuration.
