# birkhofflee/dotfiles architecture

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

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

## Overview

This project is a comprehensive set of declarative macOS dotfiles that uses Nix, nix-darwin, and Home Manager to configure and manage your Mac’s environment. The overall purpose is to provide a reproducible, version-controlled system configuration for a macOS machine (specifically, for an M1 Pro running macOS Sequoia), where nearly every aspect of your environment—from packages (managed via Nix/Homebrew) to shell customizations (using zsh, p10k, tmux, etc.)—is defined in code.

##### Main Components
- Nix Ecosystem: Represent Nix itself (with its flakes and commands) as the foundation that drives reproducible builds.
- nix-darwin: A specific tool in the Nix ecosystem used to bring Nix builds into the macOS world. This sets up system-level configurations.
- Home Manager: Manages the user’s home environment (e.g., zsh, tmux, and other user-level configurations).
- Dotfiles: The declarative configuration (files in the “hosts/AlessandroMBP/home” folder) that define settings for tools like zsh (including shell scripts, aliases, completions, etc.), tmux, git, and more.
- External Tools & Packages: Tools like fzf, bat, fd, lsd, and others that are integrated into the terminal experience.
- Build/Deployment Scripts: Include the Makefile and deployment instructions detailed in the README (e.g., the darwin-rebuild calls).

##### File Structure
- Top-Level Files: Notice the common files such as .gitignore, LICENSE, Makefile, README.md, and configuration files like flake.nix.
- hosts Directory: This is key. Inside “hosts” you have a directory for the specific host (AlessandroMBP) that contains configuration files both for the system (default.nix and os-settings.nix) and for the user's home directory. Break down the “home” directory further to see individual component configurations (like ansible.nix, bundle.nix, git.nix, tmux settings, etc.).
- Organization: The tree structure indicates a modular design where each configuration (for different tools and packages) is maintained in its own file/module.

##### README for Additional Insights
- The README clearly explains that this project is about configuring macOS via Nix and nix-darwin, with additional customizations (like iTerm2 key mappings and shell customizations).
- It outlines the deployment process, providing commands for initial setup, updating, and post-major macOS upgrade procedures. This implies an iterative build and deploy cycle.
- The documentation also shows integration points where external projects (e.g., p10k for prompt customization, fzf for file navigation, and forgit for interactive git operations) come into play.

a. Main Components:
- nix-darwin: Show this as the bridge between Nix and macOS system configurations.
- Home Manager: Represent this as the user environment customizer that manages settings for zsh, tmux, editorconfig, etc.
- Host-Specific Configurations: Represent “AlessandroMBP” as a module that gathers system, package, and home configuration.
- External Dependencies/Tools: Highlight integration with external utilities (e.g., fzf, bat, ls, etc.) that enhance the shell experience.

b. Relationships and Interactions:
- That Home Manager pulls in individual user configurations from the “home” directory.

c. Architectural Patterns and Design Principles:
- Declarative Configuration: Emphasize that the entire setup is defined as code using the Nix language.
- Modularity: Each tool or configuration aspect is isolated in its own file/module which promotes maintainability and clarity.
- Idempotence and Reproducibility: The system is designed to be rebuilt reliably on any macOS machine using the same configuration definitions.

d. Relevant Technologies and Frameworks:
- Nix, nix-darwin, Home Manager (central for configuration management).
- Underlying tools such as zsh, tmux, p10k, fzf, and other CLI utilities integrated into this ecosystem.
- iTerm2’s configuration (with its specific key mappings from Terminal.itermkeymap) as an ancillary component that enhances the terminal experience.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Management Layer
    subgraph "Configuration Management Layer"
        A1["flake.nix"]:::nixstyle
        A2["flake.lock"]:::nixstyle

        subgraph "nix-darwin"
            B1["Default.nix"]:::systemstyle
            B2["os-settings.nix"]:::systemstyle
        end

        subgraph "Home Manager"
            C1["default.nix"]:::usertool
            C2["zsh default.nix"]:::usertool
            C3["zsh shell scripts"]:::usertool
            C4["ansible.nix"]:::usertool
            C5["tmux.nix"]:::usertool
            C6["git.nix"]:::usertool
        end

        %% Flakes feeding into system and user configurations
        A1 -->|"feeds"| B1
        A2 -->|"feeds"| B1
        A1 -->|"feeds"| C1
        A2 -->|"feeds"| C1
    end

    %% External Tools and Build/Deployment Scripts
    subgraph "External & Deployment"
        D1["Packages"]:::external
        E1["Terminal.itermkeymap"]:::external
        F1["Makefile"]:::script
        F2["README.md"]:::doc
    end

    %% Infrastructure Layer (macOS)
    subgraph "Infrastructure Layer"
        G1["macOS (M1 Pro, Sequoia)"]:::systemstyle
    end

    %% Relationships from nix-darwin to macOS
    B1 -->|"applies"| G1
    B2 -->|"applies"| G1

    %% Relationships from Home Manager dotfiles to macOS user environment
    C1 -->|"configures"| G1
    C2 -->|"configures"| G1
    C3 -->|"configures"| G1
    C4 -->|"configures"| G1
    C5 -->|"configures"| G1
    C6 -->|"configures"| G1

    %% Build/Deployment triggering configuration
    F1 -->|"triggers"| A1
    F1 -->|"triggers"| B1
    F1 -->|"triggers"| C1
    F2 -->|"guides"| A1

    %% External integrations
    D1 -->|"integrates with"| C1
    D1 -->|"integrates with"| B1
    E1 -->|"enhances"| G1

    %% Styles
    classDef nixstyle fill:#FFF3B0,stroke:#333,stroke-width:2px;
    classDef systemstyle fill:#FFCCCB,stroke:#333,stroke-width:2px;
    classDef usertool fill:#C7E7FF,stroke:#333,stroke-width:2px;
    classDef external fill:#D4EDDA,stroke:#333,stroke-width:2px;
    classDef script fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef doc fill:#FFE0B2,stroke:#333,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/birkhofflee/dotfiles/blob/master/flake.nix"
    click A2 "https://github.com/birkhofflee/dotfiles/blob/master/flake.lock"
    click B1 "https://github.com/birkhofflee/dotfiles/blob/master/hosts/AlessandroMBP/default.nix"
    click B2 "https://github.com/birkhofflee/dotfiles/blob/master/hosts/AlessandroMBP/os-settings.nix"
    click C1 "https://github.com/birkhofflee/dotfiles/blob/master/hosts/AlessandroMBP/home/default.nix"
    click C2 "https://github.com/birkhofflee/dotfiles/blob/master/hosts/AlessandroMBP/home/zsh/default.nix"
    click C3 "https://github.com/birkhofflee/dotfiles/tree/master/hosts/AlessandroMBP/home/zsh/shell/*"
    click C4 "https://github.com/birkhofflee/dotfiles/blob/master/hosts/AlessandroMBP/home/ansible.nix"
    click C5 "https://github.com/birkhofflee/dotfiles/blob/master/hosts/AlessandroMBP/home/tmux.nix"
    click C6 "https://github.com/birkhofflee/dotfiles/blob/master/hosts/AlessandroMBP/home/git.nix"
    click D1 "https://github.com/birkhofflee/dotfiles/tree/master/hosts/AlessandroMBP/packages"
    click F1 "https://github.com/birkhofflee/dotfiles/tree/master/Makefile"
    click F2 "https://github.com/birkhofflee/dotfiles/blob/master/README.md"
    click E1 "https://github.com/birkhofflee/dotfiles/blob/master/Terminal.itermkeymap"
```
