# moisesmorillo/dotfiles architecture

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

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

## Overview

##### Project Type and Purpose
- This is a personal “dotfiles” repository: a modular configuration manager for macOS and GitHub Codespaces.
- It leverages GNU Stow to symlink curated config files (ZSH, Neovim, Tmux, etc.) into your home directory.
- It also provides installation scripts, CI workflows, and cross-platform environment detection.

##### File-Structure Analysis
- Top-level “modules” directories each contain a tool’s config:
- zsh/ (aliases, options, functions)
- nvim/ (Lua-based init, plugin configs, ftplugins)
- tmux/ (themes, keybindings)
- ghostty/, starship/, brew/, docker/lazygit/lazydocker/mise/ (each tool’s config)
- scripts/ holds the various shell installers and helpers: install.sh, macOS setup, Codespaces detection, utility functions.
- .github/workflows contains CI pipelines for linting shell, YAML, Lua, and running cross-platform install tests.

##### README Insights
- Highlights modular design with GNU Stow, environment detection (macOS vs. Codespaces), and automated tests via GitHub Actions.
- Describes each module’s role: shell, editor, terminal, Tmux, prompt, container and version managers.

a. Main Components
- Environment (macOS / Codespaces)
- Installer & Scripts (install.sh + helpers)
- GNU Stow orchestrator
- Config Modules (zsh, nvim, tmux, ghostty, starship, brew, docker, lazygit, lazydocker, mise, yamlfmt, yamllint)
- CI Pipeline (GitHub Actions jobs: lint, test, validation)
- External Tools & Services (Homebrew, Docker/Colima, GitHub Codespaces)
b. Relationships & Data Flow
- Environment → invokes Installer
- Installer → uses Stow to symlink each Module into ~/
- Modules reference tool executables (ZSH, nvim, tmux, etc.)
- CI Pipeline → runs against repo on push/PR, yields pass/fail back to GitHub
- External Tools ← Modules supply configuration to these tools at runtime
c. Architectural Patterns & Principles
- Modularity: each tool’s config isolated in its own directory
- Declarative setup: “stow” defines where symlinks go without copying files
- Idempotence: install scripts and CI ensure repeatable, safe installs
- Environment detection: branching logic for Codespaces vs local macOS
d. Key Technologies & Frameworks
- GNU Stow for symlinks
- Bash shell scripts
- Lua (Neovim config)
- GitHub Actions (YAML workflows)
- Linters: ShellCheck, luacheck, yamllint

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Environment"
        Env["Environment (macOS / Codespaces)"]:::external
    end

    subgraph "Installer & Scripts"
        Install["install.sh"]:::scripts
        Utils["utils.sh"]:::scripts
        Codespaces["install-codespaces.sh"]:::scripts
        MacOSInst["install-mac.sh"]:::scripts
        MacOSSettings["macos-settings.sh"]:::scripts
        UpdateDocker["update-docker-config.sh"]:::scripts
    end

    subgraph "GNU Stow Orchestrator"
        Stowrc[".stowrc"]:::scripts
        Ignore[".stow-local-ignore"]:::scripts
    end

    subgraph "Config Modules"
        subgraph "Shell"
            Zsh["zsh module"]:::module
        end
        subgraph "Editor"
            Nvim["nvim module"]:::module
        end
        subgraph "Terminal"
            Tmux["tmux module"]:::module
        end
        subgraph "Prompt"
            Starship["starship module"]:::module
        end
        subgraph "Terminal Emulator"
            Ghostty["ghostty module"]:::module
        end
        subgraph "Package Manager"
            Brew["brew module"]:::module
        end
        subgraph "Container & Git Helpers"
            Lazygit["lazygit module"]:::module
            Lazydocker["lazydocker module"]:::module
            Mise["mise module"]:::module
        end
        subgraph "Linters & Formatters"
            Yamlfmt["yamlfmt module"]:::module
            Yamllint["yamllint module"]:::module
        end
    end

    subgraph "CI Pipeline (GitHub Actions)"
        CI["CI Pipeline"]:::ci
    end

    subgraph "External Tools & Services"
        ZSHExt["Zsh Shell"]:::external
        NVIMExt["Neovim"]:::external
        TMUXExt["Tmux"]:::external
        StarshipExt["Starship"]:::external
        GhosttyExt["Ghostty"]:::external
        BrewExt["Homebrew"]:::external
        DockerExt["Docker/Colima"]:::external
        CodespacesExt["GitHub Codespaces"]:::external
    end

    Env -->|invokes| Install
    Install -->|orchestrates| Stowrc
    Install -->|uses ignore rules| Ignore
    Stowrc -->|"symlinks"| Zsh
    Stowrc -->|"symlinks"| Nvim
    Stowrc -->|"symlinks"| Tmux
    Stowrc -->|"symlinks"| Starship
    Stowrc -->|"symlinks"| Ghostty
    Stowrc -->|"symlinks"| Brew
    Stowrc -->|"symlinks"| Lazygit
    Stowrc -->|"symlinks"| Lazydocker
    Stowrc -->|"symlinks"| Mise
    Stowrc -->|"symlinks"| Yamlfmt
    Stowrc -->|"symlinks"| Yamllint

    Zsh -->|provides config to| ZSHExt
    Nvim -->|provides config to| NVIMExt
    Tmux -->|provides config to| TMUXExt
    Starship -->|provides config to| StarshipExt
    Ghostty -->|provides config to| GhosttyExt
    Brew -->|provides Brewfile to| BrewExt
    Lazygit -->|provides config to| DockerExt
    Lazydocker -->|provides config to| DockerExt
    Mise -->|provides config to| DockerExt
    Yamlfmt -->|used by CI| CI
    Yamllint -->|used by CI| CI

    CI -->|validates scripts| Install
    CI -->|validates modules| Zsh
    CI -->|validates modules| Nvim
    CI -->|validates modules| Tmux
    CI -->|validates modules| Starship
    CI -->|validates modules| Ghostty
    CI -->|validates modules| Brew
    CI -->|validates modules| Lazygit
    CI -->|validates modules| Lazydocker
    CI -->|validates modules| Mise
    CI -->|validates modules| Yamlfmt
    CI -->|validates modules| Yamllint

    click Codespaces "https://github.com/moisesmorillo/dotfiles/blob/main/scripts/install-codespaces.sh"
    click MacOSInst "https://github.com/moisesmorillo/dotfiles/blob/main/scripts/install-mac.sh"
    click MacOSSettings "https://github.com/moisesmorillo/dotfiles/blob/main/scripts/macos-settings.sh"
    click Utils "https://github.com/moisesmorillo/dotfiles/blob/main/scripts/utils.sh"
    click Install "https://github.com/moisesmorillo/dotfiles/blob/main/install.sh"
    click UpdateDocker "https://github.com/moisesmorillo/dotfiles/blob/main/scripts/update-docker-config.sh"
    click Stowrc "https://github.com/moisesmorillo/dotfiles/blob/main/.stowrc"
    click Ignore "https://github.com/moisesmorillo/dotfiles/blob/main/.stow-local-ignore"
    click Zsh "https://github.com/moisesmorillo/dotfiles/blob/main/zsh/.zshrc"
    click Nvim "https://github.com/moisesmorillo/dotfiles/blob/main/nvim/.config/nvim/init.lua"
    click Tmux "https://github.com/moisesmorillo/dotfiles/blob/main/tmux/.tmux.conf"
    click Starship "https://github.com/moisesmorillo/dotfiles/blob/main/starship/.config/starship.toml"
    click Ghostty "https://github.com/moisesmorillo/dotfiles/tree/main/ghostty/.config/ghostty/config"
    click Brew "https://github.com/moisesmorillo/dotfiles/tree/main/brew/Brewfile"
    click Lazygit "https://github.com/moisesmorillo/dotfiles/blob/main/lazygit/.config/lazygit/config.yml"
    click Lazydocker "https://github.com/moisesmorillo/dotfiles/blob/main/lazydocker/.config/lazydocker/config.yml"
    click Mise "https://github.com/moisesmorillo/dotfiles/blob/main/mise/.config/mise/config.toml"
    click Yamlfmt "https://github.com/moisesmorillo/dotfiles/blob/main/yamlfmt/.config/yamlfmt/.yamlfmt"
    click Yamllint "https://github.com/moisesmorillo/dotfiles/tree/main/yamllint/.config/yamllint/config"
    click CI "https://github.com/moisesmorillo/dotfiles/blob/main/.github/workflows/lua.yml"

    classDef scripts fill:#9f6,stroke:#333,stroke-width:1px
    classDef module fill:#6cf,stroke:#333,stroke-width:1px
    classDef ci fill:#fc6,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
```
