# katsu996/dotfiles architecture

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

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

## Overview

##### Main Components
a. Remote Git Repository
- Hosts all your chezmoi templates and config data (GitHub: katsu996/dotfiles.git).
b. Local chezmoi CLI
- Acts as the orchestration engine: init, apply, update, diff.
c. Template Store (“chezmoi working tree”)
- Directory structure under `./home`, `.chezmoitemplates`, `.chezmoiscripts`, etc.
d. OS-Specific Package Managers & Shells
- Homebrew (macOS) or WinGet (Windows), plus shells (zsh / clink), Starship prompt, mise version manager.
e. User’s Home Directory (Target State)
- Actual dotfiles in `~/.config`, `~/.gitignore`, `~/.zshrc`, etc., derived from templates.
f. External Tools & Services (Optional)
- VSCode, Ghostty, Gemini, Claude integrations (via templates under `.gemini`, `.claude`).

##### Relationships and Data Flows
a. Git Pull → chezmoi Update
- Remote changes fetched to the local chezmoi working tree.
b. chezmoi Diff / Apply → Home Directory
- Templates are rendered (templating engine using your TOML data) and materialized as real config files.
c. OS Detection Logic
- chezmoi uses your `role` (work/personal) and OS (darwin/windows) to select the correct sub-templates.
d. onChange Hooks / Scripts
- Shell scripts in `.chezmoiscripts` run post-apply to install packages via Homebrew or WinGet.

##### Architectural Patterns
- Template-Driven Configuration: `.tmpl` files are parameterized.
- OS & Role Abstraction: Directory structure mirrors categories (common, work, personal) and platforms.
- GitOps Approach: Treat configurations as code; apply changes by pulling & syncing.

##### Technologies & Frameworks
- chezmoi (core engine)
- Git (version control)
- Homebrew / WinGet (package managers)
- Shell (zsh / clink), Starship, mise (version manager)
- VSCode, Ghostty, Claude/Gemini integrations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Remote Git Repo
    Repo["Remote Git Repository"]:::store
    click Repo "https://github.com/katsu996/dotfiles/tree/main//"
    
    %% Local chezmoi CLI & Working Tree
    subgraph "Local chezmoi CLI & Working Tree"
        CLI["chezmoi CLI &<br/>Working Tree"]:::process
        
        subgraph "Local chezmoi Configuration"
            CM1[".chezmoi.toml.tmpl"]:::store
            click CM1 "https://github.com/katsu996/dotfiles/blob/main/.chezmoi.toml.tmpl"
            CM2[".chezmoiignore"]:::store
            click CM2 "https://github.com/katsu996/dotfiles/blob/main/.chezmoiignore"
            CM3[".chezmoiroot"]:::store
            click CM3 "https://github.com/katsu996/dotfiles/blob/main/.chezmoiroot"
        end
        
        subgraph "Template Store"
            TS[".chezmoitemplates"]:::store
            click TS "https://github.com/katsu996/dotfiles/tree/main/home/.chezmoitemplates/"
            
            subgraph "mise"
                Mdir["darwin/"]:::store
                click Mdir "https://github.com/katsu996/dotfiles/tree/main/home/.chezmoitemplates/mise/darwin/"
                Mwin["windows/"]:::store
                click Mwin "https://github.com/katsu996/dotfiles/tree/main/home/.chezmoitemplates/mise/windows/"
                
                personalDar["darwin-personal.tmpl"]:::store
                click personalDar "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoitemplates/mise/darwin/mise-darwin-personal.tmpl"
                workDar["darwin-work.tmpl"]:::store
                click workDar "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoitemplates/mise/darwin/mise-darwin-work.tmpl"
                commonDar["mise-darwin.tmpl"]:::store
                click commonDar "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoitemplates/mise/mise-darwin.tmpl"
                
                personalWin["windows-personal.tmpl"]:::store
                click personalWin "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoitemplates/mise/windows/mise-windows-personal.tmpl"
                workWin["windows-work.tmpl"]:::store
                click workWin "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoitemplates/mise/windows/mise-windows-work.tmpl"
                commonWin["mise-windows.tmpl"]:::store
                click commonWin "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoitemplates/mise/mise-windows.tmpl"
            end
            
            subgraph "starship"
                Sdir["starship"]:::store
                click Sdir "https://github.com/katsu996/dotfiles/tree/main/home/.chezmoitemplates/starship/"
                spDar["starship-darwin.toml.tmpl"]:::store
                click spDar "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoitemplates/starship/starship-darwin.toml.tmpl"
                spWin["starship-windows.toml.tmpl"]:::store
                click spWin "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoitemplates/starship/starship-windows.toml.tmpl"
            end
        end
        
        subgraph "OnChange Scripts"
            OSdir[".chezmoiscripts"]:::process
            click OSdir "https://github.com/katsu996/dotfiles/tree/main/home/.chezmoiscripts/"
            S1["run_onchange_darwin-install-packages.sh.tmpl"]:::process
            click S1 "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoiscripts/run_onchange_darwin-install-packages.sh.tmpl"
            S2["run_onchange_windows-install-packages.ps1.tmpl"]:::process
            click S2 "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoiscripts/run_onchange_windows-install-packages.ps1.tmpl"
            OSdir --> S1
            OSdir --> S2
        end
        
        CLI -->|git pull| Repo
        CLI --> Renderer["Template Renderer"]:::process
        CLI --> OSdir
        Renderer --> Mdir
        Renderer --> Mwin
        Renderer --> Sdir
        OSdir --> Homebrew
        OSdir --> WinGet
    end
    
    %% Package Managers
    Homebrew["Homebrew"]:::service
    WinGet["WinGet"]:::service
    
    click Homebrew "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoidata/packages.yaml"
    click WinGet "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoidata/packages.yaml"
    
    %% Home Directory Target
    subgraph "User Home Directory (Target State)"
        HD["Home Directory"]:::store
        
        subgraph "Home Directory Templates"
            GITCFG["dot_gitconfig.tmpl"]:::store
            click GITCFG "https://github.com/katsu996/dotfiles/blob/main/home/dot_gitconfig.tmpl"
            VSC["extensions.json"]:::store
            click VSC "https://github.com/katsu996/dotfiles/blob/main/home/.config/vscode/extensions.json"
            STCFG["starship.toml.tmpl"]:::store
            click STCFG "https://github.com/katsu996/dotfiles/blob/main/home/.config/starship.toml.tmpl"
            MCFG["config.toml.tmpl"]:::store
            click MCFG "https://github.com/katsu996/dotfiles/blob/main/home/.config/mise/config.toml.tmpl"
            GHTY["ghostty/config"]:::store
            click GHTY "https://github.com/katsu996/dotfiles/tree/main/home/.config/ghostty/config"
            PKG["packages.yaml"]:::store
            click PKG "https://github.com/katsu996/dotfiles/blob/main/home/.chezmoidata/packages.yaml"
        end
        
        Renderer --> GITCFG
        Renderer --> VSC
        Renderer --> STCFG
        Renderer --> MCFG
        Renderer --> GHTY
    end
    
    %% External Tools & Services
    subgraph "External Tools & Services"
        VSApp["VSCode"]:::service
        Ghost["Ghostty"]:::service
        Claude["Claude Integration"]:::service
        click Claude "https://github.com/katsu996/dotfiles/blob/main/.claude/CLAUDE.md"
        Gemini["Gemini Integration"]:::service
        click Gemini "https://github.com/katsu996/dotfiles/blob/main/.gemini/GEMINI.md"
    end
    
    VSApp -.-> CLI
    Ghost -.-> CLI
    Claude -.-> CLI
    Gemini -.-> CLI
    
    %% Styles
    classDef store fill:#D0E1F9,stroke:#036,stroke-width:1px;
    classDef process fill:#DFF0D8,stroke:#080,stroke-width:1px;
    classDef service fill:#FFE5B4,stroke:#E65,stroke-width:1px;
```
