# dynamotn/dotfiles architecture

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

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

## Overview

##### Main Components
- Chezmoi Manager & Configuration: At the core is chezmoi’s use, indicated by files like “.chezmoi.yaml.tmpl” and numerous “.chezmoitemplates” and “.chezmoiscripts”. This is the engine that reads the repository, applies templates, and deploys configurations to the target machines.
- Home Configurations: The “home” directory (and within it, “dot_config” and subdirectories) holds user-specific configuration templates for applications (e.g., shell, git, fish, eww, etc.), organized with template files and scripts.
- System/Root Configurations: The “root” directory contains OS-level configurations (e.g., configurations under “/etc”, “/usr”, “/opt”), including systemd, network settings, and SSH troves.
- Silos and Externals: The “silos” directory is used to isolate configurations for specific tools (such as “dytoy”, “firefox”, “hyprland”, “tmux”), which may also be managed as submodules. Additionally, there are “chezmoiexternals” files which pull in configurations from external sources.
- Scripts and Build Tools: The “scripts” folder provides a series of shell scripts (like setup.sh, build_container.sh) that bootstrap, validate prerequisites, or perform updates.
- Documentation & Tools: The “docs” folder (with its subdirectories for “tools” such as package_manager.md, mise.md, etc.) offers guidance on how these configurations and deployments are handled.

##### Relationships and Interactions
- The Chezmoi Manager serves as the orchestrator. It reads template files (with a .tmpl extension) from various directories and deploys them into the correct locations on the system (e.g., home directory, system directories).
- Home/Root configurations are processed via the chezmoi engine to generate the final dotfiles used by running applications.
- Scripts interact with both the repository and the underlying system to perform first-time setup and periodic updates.
- Externals like Git submodules and separate tool configurations (found in “silos” and “chezmoiexternals”) are integrated, ensuring that configurations from independent repositories form a cohesive part of the overall system.

##### Architectural Patterns and Design Principles
- Templating & Automation: Use of shell templates (.tmpl) shows a templating design that encourages automation and reusability across different machines.
- Separation of Concerns: The repository is organized by purpose (home, root, silos, etc.), clearly separating user configurations from system configurations.
- Extensibility via Git Submodules & Externals: The repository integrates external tools and configurations, reflecting a modular design that makes it easy to extend or update parts of the system independently.
- Script-driven Orchestration: The existence of multiple “run_once” and “run_onchange” scripts reflects an opinionated, stepwise deployment process integrated into chezmoi’s flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Chezmoi Manager Cluster
    subgraph "Chezmoi Manager"
        ChezmoiManager["Chezmoi Manager"]:::manager
    end

    %% Home Configurations Cluster
    subgraph "Home Configurations"
        HomeMain["home"]:::home
        DotConfig["dot_config"]:::home
        HomeExt[".chezmoiexternals"]:::home
        HomeScripts[".chezmoiscripts"]:::home
        HomeTemplates[".chezmoitemplates"]:::home
    end

    %% System/Root Configurations Cluster
    subgraph "System/Root Configurations"
        RootMain["root"]:::system
        RootExternal[".chezmoiexternal.yaml.tmpl"]:::system
        RootTemplates[".chezmoitemplates"]:::system
        RootETC["etc"]:::system
        RootUSR["usr"]:::system
        RootOPT["opt"]:::system
    end

    %% Silos and Externals Cluster
    subgraph "Silos and Externals"
        SilosMain["silos"]:::silos
        SilosDytoy["dytoy"]:::silos
        SilosEww["eww"]:::silos
        SilosFirefox["firefox"]:::silos
    end

    %% Scripts & Automation Cluster
    subgraph "Scripts & Automation"
        ScriptsMain["scripts"]:::scripts
        BuildContainer["build_container.sh"]:::scripts
        SetupScript["setup.sh"]:::scripts
    end

    %% Documentation & Tools Cluster
    subgraph "Documentation & Tools"
        DocsMain["docs"]:::docs
        DocsTools["tools"]:::docs
    end

    %% Relationships
    ChezmoiManager -->|"deploys"| HomeMain
    ChezmoiManager -->|"deploys"| RootMain
    ChezmoiManager -->|"integrates"| SilosMain
    ChezmoiManager <-->|"triggers"| ScriptsMain
    DocsMain -->|"supports"| ChezmoiManager

    %% Home Configurations internal flow
    HomeMain -->|"includes"| DotConfig
    HomeMain -->|"includes"| HomeExt
    HomeMain -->|"includes"| HomeScripts
    HomeMain -->|"includes"| HomeTemplates

    %% System/Root Configurations internal flow
    RootMain -->|"includes"| RootExternal
    RootMain -->|"includes"| RootTemplates
    RootMain -->|"includes"| RootETC
    RootMain -->|"includes"| RootUSR
    RootMain -->|"includes"| RootOPT

    %% Silos Cluster internal flow
    SilosMain -->|"contains"| SilosDytoy
    SilosMain -->|"contains"| SilosEww
    SilosMain -->|"contains"| SilosFirefox

    %% Scripts Cluster internal flow
    ScriptsMain -->|"contains"| BuildContainer
    ScriptsMain -->|"contains"| SetupScript

    %% Click Events for Chezmoi Manager & Configuration
    click ChezmoiManager "https://github.com/dynamotn/dotfiles/blob/main/.chezmoi.yaml.tmpl"
    click ChezmoiManager "https://github.com/dynamotn/dotfiles/blob/main/.chezmoiversion"
    click ChezmoiManager "https://github.com/dynamotn/dotfiles/blob/main/.chezmoiroot"

    %% Click Events for Home Configurations
    click HomeMain "https://github.com/dynamotn/dotfiles/tree/main/home"
    click DotConfig "https://github.com/dynamotn/dotfiles/tree/main/home/dot_config"
    click HomeExt "https://github.com/dynamotn/dotfiles/blob/main/home/.chezmoiexternals"
    click HomeScripts "https://github.com/dynamotn/dotfiles/blob/main/home/.chezmoiscripts"
    click HomeTemplates "https://github.com/dynamotn/dotfiles/blob/main/home/.chezmoitemplates"

    %% Click Events for System/Root Configurations
    click RootMain "https://github.com/dynamotn/dotfiles/tree/main/root"
    click RootExternal "https://github.com/dynamotn/dotfiles/blob/main/root/.chezmoiexternal.yaml.tmpl"
    click RootTemplates "https://github.com/dynamotn/dotfiles/blob/main/root/.chezmoitemplates"
    click RootETC "https://github.com/dynamotn/dotfiles/tree/main/root/etc"
    click RootUSR "https://github.com/dynamotn/dotfiles/tree/main/root/usr"
    click RootOPT "https://github.com/dynamotn/dotfiles/tree/main/root/opt"

    %% Click Events for Silos and Externals
    click SilosMain "https://github.com/dynamotn/dotfiles/tree/main/silos"
    click SilosDytoy "https://github.com/dynamotn/dotfiles/tree/main/silos/dytoy"
    click SilosEww "https://github.com/dynamotn/dotfiles/tree/main/silos/eww"
    click SilosFirefox "https://github.com/dynamotn/dotfiles/tree/main/silos/firefox"

    %% Click Events for Scripts & Automation
    click ScriptsMain "https://github.com/dynamotn/dotfiles/tree/main/scripts"
    click BuildContainer "https://github.com/dynamotn/dotfiles/blob/main/scripts/build_container.sh"
    click SetupScript "https://github.com/dynamotn/dotfiles/blob/main/scripts/setup.sh"

    %% Click Events for Documentation & Tools
    click DocsMain "https://github.com/dynamotn/dotfiles/tree/main/docs"
    click DocsTools "https://github.com/dynamotn/dotfiles/tree/main/docs/tools"

    %% Styles
    classDef manager fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef home fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef system fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef silos fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef scripts fill:#FF6347,stroke:#000,stroke-width:2px;
    classDef docs fill:#FFFFE0,stroke:#000,stroke-width:2px;
```
