# quintisimo/mac-nix-config architecture

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

- Interactive diagram: https://gitdiagram.com/quintisimo/mac-nix-config
- Repository: https://github.com/quintisimo/mac-nix-config

## Overview

##### Project type and purpose
- This is a declarative “dotfiles”/macOS system configuration project using Nix (nix-darwin + home-manager).
- Its goal is to manage and reproduce a user’s macOS environment (packages, secrets, VSCode settings, system services) purely in Nix.

##### File structure
Top-level files
- README.md      – setup instructions
- flake.nix      – entry point of the Nix flake
- flake.lock     – locked flake inputs
- agents.nix     – agenix configuration helper
- dock.nix       – dock layout module
- home.nix       – home-manager configuration
Directories
- packages/      – custom package sets (casks, mas, nix pkgs)
- secrets/       – encrypted secrets (secrets.nix + secrets.age)
- vscode/        – VSCode extensions & settings modules

##### README for operational flow
- Install Nix via a bootstrap script
- Clone into /etc/nix-darwin
- Run `darwin-rebuild switch` to apply system configuration
- Use agenix to decrypt/encrypt secrets

##### Main components & interactions
a. Flake Entry Point (flake.nix)
– Declares inputs: nixpkgs, darwin modules, agenix tool
– References local modules (agents.nix, dock.nix, home.nix, packages, secrets, vscode)
b. Nix Flake Resolution
– Lock file (flake.lock) ensures reproducible dependencies
c. Module Layers
– System modules (dock.nix, agents.nix) feed into darwin-rebuild
– Home-manager module (home.nix) configures user-level dotfiles and services
– Package sets (packages/casks.nix, mas.nix, nix.nix)
– VSCode settings & extensions (vscode/settings.nix, extensions.nix)
d. Secret Management
– agenix (external tool) decrypts secrets.age → secrets.nix → consumed by Nix modules
e. Output & Deployment
– `sudo darwin-rebuild switch` applies system config (launchd services, brew casks, dock layout)
– `home-manager switch` (implicit via darwin) applies user packages and dotfiles

##### Architectural patterns & design principles
- Declarative layering: Separate system vs. user vs. secret concerns
- Reproducibility via flake.lock
- Extensibility: each module (dock, vscode, packages) can be added/removed
- Security: encrypted secrets module

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs
    Shell["User Shell (CLI)"]:::external

    %% Nix Flake Core
    subgraph "Nix Flake" 
        direction TB
        Flake["flake.nix"]:::core
        Lock(("flake.lock")):::core
        Flake -->|"resolves"| Lock
    end

    %% Modules within Flake
    subgraph "Modules" 
        direction TB
        subgraph "System Modules"
            direction TB
            Agents["agents.nix"]:::core
            Dock["dock.nix"]:::core
        end
        subgraph "User Modules"
            direction TB
            Home["home.nix"]:::user
            VS_Ext["extensions.nix"]:::user
            VS_Set["settings.nix"]:::user
        end
        subgraph "Package Sets"
            direction TB
            Casks["casks.nix"]:::core
            Mas["mas.nix"]:::core
            NixPkgs["nix.nix"]:::core
        end
        subgraph "Secrets"
            direction TB
            Age["secrets.age"]:::security
            Secrets["secrets.nix"]:::security
        end
        Flake --> Agents
        Flake --> Dock
        Flake --> Home
        Flake --> Casks
        Flake --> Mas
        Flake --> NixPkgs
        Flake --> VS_Ext
        Flake --> VS_Set
        Flake --> Secrets
    end

    %% External Tools
    Agenix(("agenix")):::external
    Shell -.->|decrypts| Agenix
    Agenix -->|"decrypts"| Age
    Age -->|"produces"| Secrets

    %% Build Store
    Store(("Nix Store")):::core

    %% Build Flow
    Agents --> Store
    Dock --> Store
    Home --> Store
    Casks --> Store
    Mas --> Store
    NixPkgs --> Store
    VS_Ext --> Store
    VS_Set --> Store
    Secrets --> Store

    %% Deployment
    Darwin(("darwin-rebuild switch")):::external
    Store -->|"applies"| Darwin
    Shell -.->|runs| Darwin

    HomeMgr(("home-manager switch")):::external
    Store -->|"applies"| HomeMgr

    subgraph "macOS Targets"
        direction TB
        Sys["macOS System Services & Dock"]:::macos
        HomeDir["User Home Directory"]:::macos
    end

    Darwin -->|"configures"| Sys
    HomeMgr -->|"configures"| HomeDir

    %% Click Events
    click Flake "https://github.com/quintisimo/mac-nix-config/blob/master/flake.nix"
    click Lock "https://github.com/quintisimo/mac-nix-config/blob/master/flake.lock"
    click Agents "https://github.com/quintisimo/mac-nix-config/blob/master/agents.nix"
    click Dock "https://github.com/quintisimo/mac-nix-config/blob/master/dock.nix"
    click Home "https://github.com/quintisimo/mac-nix-config/blob/master/home.nix"
    click Casks "https://github.com/quintisimo/mac-nix-config/blob/master/packages/casks.nix"
    click Mas "https://github.com/quintisimo/mac-nix-config/blob/master/packages/mas.nix"
    click NixPkgs "https://github.com/quintisimo/mac-nix-config/blob/master/packages/nix.nix"
    click Age "https://github.com/quintisimo/mac-nix-config/blob/master/secrets/secrets.age"
    click Secrets "https://github.com/quintisimo/mac-nix-config/blob/master/secrets/secrets.nix"
    click VS_Ext "https://github.com/quintisimo/mac-nix-config/blob/master/vscode/extensions.nix"
    click VS_Set "https://github.com/quintisimo/mac-nix-config/blob/master/vscode/settings.nix"

    %% Styling
    classDef core fill:#AED6F1,stroke:#34495E
    classDef user fill:#F9E79F,stroke:#B7950B
    classDef macos fill:#ABEBC6,stroke:#1D8348
    classDef security fill:#F5B7B1,stroke:#922B21
    classDef external fill:#D5DBDB,stroke:#566573,stroke-dasharray: 5 5
```
