# sam-mahoney/nix architecture

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

- Interactive diagram: https://gitdiagram.com/sam-mahoney/nix
- Repository: https://github.com/sam-mahoney/nix

## Overview

##### Main Components
- flake.nix (Entrypoint): This file is the single source of truth that ties together all the configurations, inputs, and outputs (for NixOS, nix-darwin, and Home Manager). It sets up the relationships to the other parts of the project.
- machines/ Directory: Contains machine-specific configuration directories (for “halcyon” and “helios”). Each machine dimension directory includes its own default.nix file which serves as the entrypoint for that machine’s configuration.
- homemgr/ Directory: Holds Home Manager configurations. There are further subdirectories here that separate out components (like “mahoney” and then more subdivisions such as “halcyon” and “helios”) for specific machine or purpose targeting.
- modules/ Directory: This directory comprises reusable, platform-specific modules. It is organized into a couple of layers (common utilities, and programs–each with its own configuration such as for alacritty, bat, direnv, etc.). Each subdirectory typically includes a default.nix so that it can be imported as a module into the main configurations.
- overlays/ Directory: Contains Nix overlays to customize or extend functionality, following the same pattern (an entry file default.nix).

##### Relationships and Interactions
- The modules provide configurations for various programs (e.g., alacritty, neovim, git, tmux, etc.) and common scripts, which then are applied within situations like configuring terminals, shell environments, and development tools for the target machines.

##### Architectural Patterns and Design Principles
- Modularity: The project is highly modular, with a clear separation between machine-specific configurations, reusable modules, and overlays. Each directory with a default.nix acts as an entry point.
- Declarative Configuration: Leveraging Nix Flakes means that the entire configuration is declarative, ensuring reproducibility across systems.
- Separation of Concerns: The architecture separates system-level configurations (machines/) from user-level configurations (homemgr/) and reusable building blocks (modules/).

##### Relevant Technologies/Frameworks
- Nix/NixOS: As the foundation for system configuration.
- Nix Flakes: For managing reproducible and composable configurations.
- Home Manager: For configuring user-level settings (especially for nix-darwin and possibly NixOS).

## Diagram (Mermaid)

```mermaid
flowchart TD
    flake["flake.nix"]:::root

    subgraph "System Configurations (machines/)"
        machineHalcyon["halcyon configuration"]:::system
        machineHelios["helios configuration"]:::system
    end

    subgraph "User Configurations (homemgr/)"
        homemgrHalcyon["halcyon Home Manager"]:::user
        homemgrHelios["helios Home Manager"]:::user
    end

    subgraph "Reusable Modules"
        ModuleCommon["Common Utilities"]:::modules
        subgraph "Program Configurations"
            ModAlacritty["alacritty"]:::modules
            ModAtuin["atuin"]:::modules
            ModBat["bat"]:::modules
            ModDirenv["direnv"]:::modules
            ModFastfetch["fastfetch"]:::modules
            ModFzf["fzf"]:::modules
            ModGit["git"]:::modules
            ModGo["go"]:::modules
            ModGpg["gpg"]:::modules
            ModNeovim["neovim"]:::modules
            ModStarship["starship"]:::modules
            ModTmux["tmux"]:::modules
            ModZsh["zsh"]:::modules
        end
        ModuleScripts["Reusable Scripts"]:::modules
    end

    subgraph "Overlays"
        Overlays["Overlays"]:::overlay
    end

    %% Relationships from flake.nix
    flake -->|"imports"| machineHalcyon
    flake -->|"imports"| machineHelios
    flake -->|"imports"| homemgrHalcyon
    flake -->|"imports"| homemgrHelios
    flake -->|"imports"| ModuleCommon
    flake -->|"imports"| Overlays

    %% Relationships from machines to modules
    machineHalcyon -->|"imports"| ModuleCommon
    machineHelios -->|"imports"| ModuleCommon
    machineHalcyon -->|"imports"| ModGit
    machineHelios -->|"imports"| ModTmux

    %% Relationships from Home Manager configurations to modules
    homemgrHalcyon -->|"applies"| ModuleCommon
    homemgrHelios -->|"applies"| ModuleCommon
    homemgrHalcyon -->|"applies"| ModuleScripts
    homemgrHelios -->|"applies"| ModuleScripts
    homemgrHalcyon -->|"applies"| ModAlacritty
    homemgrHelios -->|"applies"| ModNeovim

    %% Overlays modifying modules
    Overlays -->|"overrides"| ModuleCommon
    Overlays -->|"overrides"| ModuleScripts

    %% Click Events
    click flake "https://github.com/sam-mahoney/nix/blob/master/flake.nix"
    click machineHalcyon "https://github.com/sam-mahoney/nix/blob/master/machines/halcyon/default.nix"
    click machineHelios "https://github.com/sam-mahoney/nix/blob/master/machines/helios/default.nix"
    click homemgrHalcyon "https://github.com/sam-mahoney/nix/blob/master/homemgr/mahoney/halcyon/default.nix"
    click homemgrHelios "https://github.com/sam-mahoney/nix/blob/master/homemgr/mahoney/helios/default.nix"
    click ModuleCommon "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/common/default.nix"
    click ModAlacritty "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/alacritty/default.nix"
    click ModAtuin "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/atuin/default.nix"
    click ModBat "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/bat/default.nix"
    click ModDirenv "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/direnv/default.nix"
    click ModFastfetch "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/fastfetch/default.nix"
    click ModFzf "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/fzf/default.nix"
    click ModGit "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/git/default.nix"
    click ModGo "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/go/default.nix"
    click ModGpg "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/gpg/default.nix"
    click ModNeovim "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/neovim/default.nix"
    click ModStarship "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/starship/default.nix"
    click ModTmux "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/tmux/default.nix"
    click ModZsh "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/programs/zsh/default.nix"
    click ModuleScripts "https://github.com/sam-mahoney/nix/blob/master/modules/home-manager/scripts/default.nix"
    click Overlays "https://github.com/sam-mahoney/nix/blob/master/overlays/default.nix"

    %% Styles
    classDef root fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef system fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef user fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef modules fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef overlay fill:#FFA500,stroke:#000,stroke-width:1px;
```
