# scottames/dots architecture

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

- Interactive diagram: https://gitdiagram.com/scottames/dots
- Repository: https://github.com/scottames/dots

## Overview

##### Project Type and Purpose
- This is an open-source “dotfiles” repository designed to manage user configuration across multiple machines (Linux and MacOS).
- It leverages chezmoi for templated file deployment, nix flakes on Mac, mage for task automation, aqua for version management, and GitHub Actions for CI/CD.

##### High-Level Components
a. Source Control (GitHub)
- Repository hosting all code and config files
- GitHub Actions workflows under `.github/workflows` and Trunk configuration under `.trunk`
b. Configuration Management Engines
- Chezmoi – renders `home/` templates to actual dotfiles in the user’s home directory
- Nix Flake (`flake.nix`) – MacOS configuration with nix-darwin
c. Task Automation
- Magefiles (`magefiles/`) – Go-based scripts to build, test, lint, and generate assets
- Shell scripts (`scripts/init.sh`) – bootstrap installer for initial setup
d. Versioned Toolchain Declarations
- Aqua (`aqua/*.yaml`) – declarative specification of CLI tool versions
e. Helper Libraries
- Go helper package (`pkg/helpers`) – utilities for file operations, shell execution, Git interactions
f. Local Target Environment
- User home directory (rendered dotfiles, private vs. public templates, executable scripts in `home/bin`)
- Private overrides (`home/private_dot_config`, `home/private_dot_zsh`, etc.)
g. CI/CD and Testing
- Docker container used by `mage test` to run linters, Go tests, and a headless `chezmoi init`
- GitHub Actions for release, semantic versioning, dependency updates

##### Relationships and Data Flows
- Developer pushes changes → GitHub repo → triggers GitHub Actions → runs linters/tests/mage tasks
- On local machine:
- `scripts/init.sh` fetches repo → invokes chezmoi → reads `home/` templates + `.chezmoi.toml` configuration → writes actual dotfiles
- On Mac: nix flake (`nix run .#install`) builds and deploys Mac-specific modules
- Mage commands orchestrate Docker-based tests, code generation, policy checks (via aqua), system tweaks (via gsettings.go)
- Aqua reads its YAML registry → installs or pins CLI tools under `~/.local/share/aqua/`
- Helper functions (`pkg/helpers`) are used by magefiles and by any future Go-based extensions.

##### Architectural Patterns and Principles
- Template-Driven Configuration: home templates + private overrides facilitate separation of public vs. private settings.
- Infrastructure-as-Code: nix flake and aqua YAML manifest the environment declaratively.
- Task Orchestration via Code: magefiles centralize build, test, and CI logic in Go.
- CI/CD as Code: workflows and trunk analyzers enforce linting and versioning policies automatically.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GitHub & CI/CD"
        GH["GitHub Repo"]:::external
        WFS[".github/workflows"]:::source
        TRUNK[".trunk"]:::source
        GH -->|"push code"| WFS
        GH -->|"push code"| TRUNK
    end

    subgraph "Developer Local Machine"
        BS["scripts/init.sh"]:::source
        MAGE["Mage CLI\n(magefiles)"]:::source
        NIX["flake.nix\n(Nix Flake)"]:::config
        BS -->|"bootstrap init"| CHEZ
        BS -->|"bootstrap init"| MAGE
        MAGE -->|"runs tasks"| CHEZ
        MAGE -->|"mage test"| DOCKER
        NIX -->|"nix run .#install"| HOME
    end

    subgraph "Configuration Engines"
        CHEZ["Chezmoi"]:::config
        AQUA["Aqua"]:::config
        CHEZ -->|"render templates"| HOME
        AQUA -->|"install CLI tools"| HOME
    end

    subgraph "Target Home Environment"
        HOME["User Home Directory"]:::runtime
    end

    DOCKER["Docker Container\nfor Testing"]:::runtime
    DOCKER -->|"test results"| MAGE

    WFS -->|"trigger CI/CD"| DOCKER

    %% Click Events
    click WFS "https://github.com/scottames/dots/tree/main/.github/workflows"
    click TRUNK "https://github.com/scottames/dots/blob/main/.trunk"
    click BS "https://github.com/scottames/dots/blob/main/scripts/init.sh"
    click MAGE "https://github.com/scottames/dots/tree/main/magefiles"
    click NIX "https://github.com/scottames/dots/blob/main/flake.nix"
    click AQUA "https://github.com/scottames/dots/tree/main/aqua"
    click CHEZ "https://github.com/scottames/dots/tree/main/home"
    click HOME "https://github.com/scottames/dots/tree/main/home"
    click DOCKER "https://github.com/scottames/dots/tree/main/assets/docker/archlinux/Dockerfile"

    %% Styles
    classDef source fill:#a6c8ff,stroke:#000,color:#000
    classDef config fill:#b7e4c7,stroke:#000,color:#000
    classDef runtime fill:#ffd6a5,stroke:#000,color:#000
    classDef external fill:#e0e0e0,stroke:#000,color:#000
```
