# sandptel/regolith-nix architecture

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

- Interactive diagram: https://gitdiagram.com/sandptel/regolith-nix
- Repository: https://github.com/sandptel/regolith-nix

## Overview

##### Project Type & Purpose
- This is an “infrastructure‐as‐code”/configuration‐management project using Nix flakes.
- Its goal is to package, patch, and expose Regolith (i3/Sway desktop + ecosystem) as a reusable NixOS module and development shell.

##### File Structure
- Top-level:
- flake.nix, flake.lock – the root flake defining inputs, outputs, modules, and dev shells.
- README.md – usage instructions (installing Nix, using the flake).
- modules/ – NixOS module definitions, e.g., modules/regolith.nix.
- packages/ – individual Nix derivations for Regolith components (i3‐swap‐focus, i3status‐rs, regolith‐powerd, etc.).
- sway-regolith/ – an overlay with patches and a series file to modify the upstream sway‐regolith package.
- testing/ – a separate flake for CI/test configurations (home-manager and NixOS configs).
- regolith-look-* & regolith-powerd directories – local build artifacts or additional overlays.

##### README for Insights
- Inputs: nixpkgs, home-manager, regolith (this repo).
- Outputs:
- nixosConfigurations.<name> – a NixOS module that, when enabled, brings in all Regolith packages and sets up the desktop session.
- devShell (“nix develop”) containing all tooling.
- External services: Cachix for binary cache, Nix’s flakes feature.

##### Main Components & Their Relationships
a. Flake Root (flake.nix)
- Declares inputs: nixpkgs, home-manager, regolith.
- Exposes outputs: NixOS module, devShell, package set.
b. NixOS Module (modules/regolith.nix)
- Configures system.packages, services, sway session, input, status bar, etc.
- Pulls in packages from packages/ and the overlay sway-regolith.
c. Packages/Overlays
- packages/*: Nix derivations for each Regolith component.
- sway-regolith overlay: patches to upstream sway‐regolith, series for nixpkgs overlay.
d. Testing Flake (testing/flake.nix)
- Uses this repo as input; defines two test configurations:
- home-manager test shell
- NixOS VM config + hardware config for CI.
e. External Dependencies
- Cachix: binary cache endpoint.
- nixpkgs & home-manager: upstream flakes.
- nix daemon/CLI with flakes enabled.

##### Architectural Patterns & Principles
- Declarative configuration: represent flake.nix as the single source of truth.
- Overlays: show how sway-regolith feeds into nixpkgs to alter package derivations.
- Modularity: modules/ holds the NixOS module, packages/ holds individual derivations.
- Testing as code: separate flake under testing/ that depends on the main flake.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Inputs
    subgraph "Inputs"
        NP["nixpkgs@nixos-24.05"]:::inputs
        HM["home-manager@commit"]:::inputs
        CX["Cachix (binary cache)"]:::inputs
    end

    %% Documentation
    README["README.md"]:::core
    click README "https://github.com/sandptel/regolith-nix/blob/dev/README.md"

    %% Flake Root
    FR["Flake Root\n(flake.nix & flake.lock)"]:::core
    click FR "https://github.com/sandptel/regolith-nix/blob/dev/flake.nix"
    click FR "https://github.com/sandptel/regolith-nix/blob/dev/flake.lock"

    NP -->|"input"| FR
    HM -->|"input"| FR
    CX -->|"binary cache"| FR
    README -->|"doc for"| FR

    %% Core Modules & Packages
    subgraph "Core Modules & Packages"
        MOD["modules/regolith.nix"]:::packages
        PKGS["packages/"]:::packages
        SW["sway-regolith Overlay"]:::packages
        LBA["Local Build Artifacts"]:::packages
    end
    click MOD "https://github.com/sandptel/regolith-nix/blob/dev/modules/regolith.nix"
    click PKGS "https://github.com/sandptel/regolith-nix/tree/dev/packages/"
    click SW "https://github.com/sandptel/regolith-nix/blob/dev/sway-regolith/overlay.nix"
    click LBA "https://github.com/sandptel/regolith-nix/blob/dev/regolith-look-default/default.nix"

    FR -->|"includes"| MOD
    FR -->|"includes"| PKGS
    FR -->|"includes"| SW
    FR -->|"includes"| LBA

    %% Testing Flake
    subgraph "Testing Flake"
        TF["testing/flake.nix"]:::packages
    end
    click TF "https://github.com/sandptel/regolith-nix/blob/dev/testing/flake.nix"

    FR -->|"input to"| TF

    %% Outputs
    subgraph "Outputs"
        NOZ["nixosConfigurations.<host>"]:::outputs
        DS["devShell"]:::outputs
        PS["packages.default"]:::outputs
        TS["tests (home-manager & NixOS)"]:::outputs
    end

    FR -->|"provides"| NOZ
    FR -->|"provides"| DS
    FR -->|"provides"| PS
    TF -->|"generates"| TS

    %% Deployment Target
    VM["NixOS VM"]:::external
    NOZ -->|"deploys to"| VM

    %% Legend
    subgraph "Legend"
        direction LR
        I["Inputs (blue)"]:::inputs
        C["Core/Root (purple)"]:::core
        P["Packages/Modules (green)"]:::packages
        O["Outputs (orange)"]:::outputs
        E["External (gray)"]:::external
    end

    %% Styles
    classDef inputs fill:#AED6F1,stroke:#21618C,color:#1B2631
    classDef core fill:#D2B4DE,stroke:#7D3C98,color:#1B2631
    classDef packages fill:#ABEBC6,stroke:#239B56,color:#1B2631
    classDef outputs fill:#F9E79F,stroke:#B7950B,color:#1B2631
    classDef external fill:#D5D8DC,stroke:#5D6D7E,color:#1B2631
```
