# mic92/dotfiles architecture

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

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

## Overview

##### Project type and purpose
- This is not a typical application but a monorepo for “infrastructure-as-code” and personal dotfiles. It uses Nix flakes, Home-Manager, NixOS modules, Terraform, SOPS and other tool-specific submodules (e.g. fish, zsh, GDB, Darwin, OpenWRT).
- Purpose: declare and bootstrap reproducible system configurations (local dev shells, laptops, servers, routers, cloud bots) from a single Git repository.

##### File-structure analysis
- Top-level:
- flake.nix & flake.lock – entrypoint of Nix flakes
- Readme.md, LICENSE, CI workflows (.github)
- tasks.py – custom orchestration
- Submodules:
- home-manager/ – per-user Nix Home-Manager config
- nixosModules/ – reusable NixOS modules
- darwinModules/ – macOS configuration
- openwrt/ – router provisioning via Nix
- machines/ – host-specific NixOS system configurations
- terraform/ – cloud infrastructure definitions
- sops/ & secrets/ – encrypted secret storage
- devshell/, fish/, zsh/, gdb/ – dev environment helpers
- pkgs/ – in-repo Nix package and image definitions
- CI: GitHub Actions automate dependency updates, submodule sync, auto-merge.

##### README insights
- Invoking `nix run github:Mic92/dotfiles` bootstraps everything.
- Describes bootstrapping steps for Nix (single/multi-user), Home-Manager, legacy OS fallback.

a. Git repository (source of truth)
b. CI/CD plane: GitHub Actions
c. IaC plane:
- Nix flakes entrypoint → flake.nix
- Terraform modules under terraform/
- SOPS secrets decrypted into Nix config
- tasks.py orchestrating niche workflows
d. Configuration modules:
- NixOS modules (nixosModules/)
- Home-Manager modules (home-manager/)
- Darwin modules (darwinModules/)
- OpenWRT modules (openwrt/)
- Dev environment modules (devshell/, fish/, zsh/, gdb/)
e. Target nodes:
- Local developer workstation (devshell, interactive shells)
- Remote NixOS hosts (machines/*)
- Cloud services or bots (via terraform/github-bots)
f. Secrets management: SOPS (age keys, group definitions)

##### Relationships and data flows
- Developer pushes to GitHub → triggers CI workflows (update-deps, auto-merge).
- CI updates flake.lock and may open PRs.
- Developer or CI runs `nix flake` which:
- Decrypts secrets via SOPS → feeds into Nix evaluation
- Builds Home-Manager profile for user
- Builds NixOS system closures for each machine
- Builds Darwin and OpenWRT configurations
- Builds devshell environments and Nix packages in pkgs/
- Runs Terraform to provision cloud resources and bots
- Outputs:
- System configurations applied via `home-manager switch`, `nixos-rebuild`, `terraform apply`, or manual SSH+flake deploy.

##### Architectural patterns and principles
- Monorepo: single source for all environments
- Flake-driven reproducibility: pinning all inputs via flake.lock
- Modular config: reusable NixOS modules & Home-Manager modules
- Secrets-as-code: SOPS encryption integrated into Nix
- CI-first: GitHub Actions keep flakes and submodules up-to-date

##### Detail level
- Per-OS modules (nixosModules/, darwinModules/, openwrt/) into a single “OS modules” component.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Repository
    subgraph "Repository"
        R["Git Repository"]:::code
        FQ["flake.nix & flake.lock"]:::code
        TS["tasks.py"]:::code
    end

    %% CI/CD
    subgraph "CI/CD Plane"
        CI["GitHub Actions"]:::ci
    end

    %% Secrets
    subgraph "Secrets Management (SOPS)"
        SG["Group Definitions"]:::secret
        SK["Machine Keys"]:::secret
        SE["Encrypted Secrets"]:::secret
    end

    %% Configuration Modules
    subgraph "Configuration Modules" 
        NM["NixOS Modules"]:::modules
        HM["Home-Manager Modules"]:::modules
        DM["Darwin Modules"]:::modules
        OM["OpenWRT Modules"]:::modules
        DE["Dev Environment Helpers"]:::modules
        PK["In-Repo Nix Packages"]:::modules
        FS["Fish Shell"]:::modules
        ZS["Zsh Plugins"]:::modules
        GB["GDB Extensions"]:::modules
    end

    %% Terraform Plane
    subgraph "Terraform Infrastructure Plane"
        TF["Terraform Root Config"]:::cloud
        TM["Terraform Modules"]:::cloud
        TB["GitHub Bots Infra"]:::cloud
        TL["GitLab Infra"]:::cloud
    end

    %% Evaluation
    NixEval["Nix Flake Evaluation"]:::process

    %% Targets
    subgraph "Provisioned Targets"
        DW["Developer Workstation"]:::target
        NH["NixOS Hosts"]:::target
        MH["macOS Host"]:::target
        OR["OpenWRT Router"]:::target
        CIb["Cloud Infra & Bots"]:::cloud
    end

    %% Connections
    R --> CI
    CI -->|updates flake.lock| R
    R --> FQ
    R --> TS

    CI --> SG
    SG --> CI

    SG --> NixEval
    SK --> NixEval
    SE --> NixEval

    FQ --> NixEval
    TS --> NixEval

    NM --> NixEval
    HM --> NixEval
    DM --> NixEval
    OM --> NixEval
    DE --> NixEval
    PK --> NixEval
    FS --> NixEval
    ZS --> NixEval
    GB --> NixEval

    NixEval --> DW
    NixEval --> NH
    NixEval --> MH
    NixEval --> OR

    NixEval --> TF
    TF --> TM
    TF --> TB
    TF --> TL
    TB --> CIb

    %% Click Events
    click R "https://github.com/mic92/dotfiles/tree/main//"
    click CI "https://github.com/mic92/dotfiles/blob/main//.github/workflows/auto-merge.yaml"
    click FQ "https://github.com/mic92/dotfiles/blob/main//flake.nix"
    click TS "https://github.com/mic92/dotfiles/blob/main//tasks.py"
    click SG "https://github.com/mic92/dotfiles/tree/main//sops/groups/"
    click SK "https://github.com/mic92/dotfiles/tree/main//sops/machines/"
    click SE "https://github.com/mic92/dotfiles/tree/main//sops/secrets/"
    click NM "https://github.com/mic92/dotfiles/tree/main//nixosModules/"
    click HM "https://github.com/mic92/dotfiles/tree/main//home-manager/"
    click DM "https://github.com/mic92/dotfiles/tree/main//darwinModules/"
    click OM "https://github.com/mic92/dotfiles/tree/main//openwrt/"
    click DE "https://github.com/mic92/dotfiles/blob/main//devshell/flake-module.nix"
    click FS "https://github.com/mic92/dotfiles/tree/main//fish/"
    click ZS "https://github.com/mic92/dotfiles/tree/main//zsh/"
    click GB "https://github.com/mic92/dotfiles/tree/main//gdb/"
    click PK "https://github.com/mic92/dotfiles/tree/main//pkgs/"
    click TF "https://github.com/mic92/dotfiles/blob/main//terraform/flake-module.nix"
    click TM "https://github.com/mic92/dotfiles/tree/main//terraform/modules/"
    click TB "https://github.com/mic92/dotfiles/tree/main//terraform/github-bots/"
    click TL "https://github.com/mic92/dotfiles/tree/main//terraform/gitlab/"

    %% Styles
    classDef code fill:#f9f,stroke:#333,stroke-width:1px
    classDef ci fill:#bbf,stroke:#333,stroke-width:1px
    classDef secret fill:#fdd,stroke:#333,stroke-width:1px
    classDef modules fill:#dfd,stroke:#333,stroke-width:1px
    classDef cloud fill:#cff,stroke:#333,stroke-width:1px
    classDef process fill:#ffd,stroke:#333,stroke-width:1px
    classDef target fill:#efe,stroke:#333,stroke-width:1px
```
