# Repository Architecture

This document provides an overview of the repository architecture, explaining how the various components fit together.

## Overview

This NixOS configuration repository is built using [Nix Flakes](https://nixos.wiki/wiki/Flakes) and [Snowfall Lib](https://github.com/snowfallorg/lib) to provide a modular, maintainable configuration for multiple systems. The Snowfall namespace is `mjallen`, so all custom options are accessed as `mjallen.<domain>.<name>`.

## Directory Structure

```
.
├── flake.nix              # Main flake — inputs, outputs, Snowfall config
├── flake.lock             # Locked dependency versions
├── .sops.yaml             # SOPS key management rules
├── treefmt.nix            # Code formatter configuration
├── qemu.nix               # QEMU VM testing config
│
├── checks/                # Pre-commit hooks and CI checks
│
├── docs/                  # Documentation (this directory)
│
├── homes/                 # Home Manager configurations
│   ├── aarch64-darwin/    # macOS user configs
│   ├── aarch64-linux/     # ARM Linux user configs
│   └── x86_64-linux/      # x86 Linux user configs
│
├── lib/                   # Custom Nix library utilities
│   ├── module/            # mkModule, mkOpt, mkBoolOpt helpers
│   ├── file/              # File/path utilities
│   └── versioning/        # Package version pinning helpers
│
├── modules/               # Reusable configuration modules
│   ├── home/              # Home Manager modules
│   ├── nixos/             # NixOS system modules
│   └── darwin/            # nix-darwin modules (macOS)
│
├── overlays/              # Nixpkgs overlays
│
├── packages/              # Custom package definitions
│
├── secrets/               # SOPS-encrypted secret files
│
└── systems/               # Per-host system configurations
    ├── aarch64-darwin/    # macOS (nix-darwin) hosts
    ├── aarch64-linux/     # ARM Linux hosts
    ├── x86_64-install-iso/# Install ISO configurations
    └── x86_64-linux/      # x86_64 Linux hosts
```

## Flake Inputs

| Input | Source | Purpose |
|---|---|---|
| `nixpkgs-unstable` | `github:NixOS/nixpkgs/nixos-unstable` | Primary package set |
| `nixpkgs-stable` | `github:NixOS/nixpkgs/nixos-25.11` | Stable package set |
| `nixpkgs-otbr` | `github:mrene/nixpkgs` (fork) | OpenThread Border Router packages |
| `home-manager-unstable` | `github:nix-community/home-manager` | User environment management |
| `snowfall-lib` | `github:mjallen18/snowfall-lib` | Flake structure library (personal fork) |
| `impermanence` | `github:nix-community/impermanence` | Ephemeral root filesystem support |
| `lanzaboote` | `github:nix-community/lanzaboote/v1.0.0` | Secure Boot |
| `nixos-hardware` | `github:NixOS/nixos-hardware` | Hardware-specific NixOS configs |
| `sops-nix` | `github:Mic92/sops-nix` | Secret management |
| `disko` | `github:nix-community/disko` | Declarative disk partitioning |
| `cosmic` | `github:lilyinstarlight/nixos-cosmic` | COSMIC desktop environment |
| `jovian` | `github:Jovian-Experiments/Jovian-NixOS` | Steam Deck / handheld support |
| `nixos-apple-silicon` | `github:nix-community/nixos-apple-silicon` | Asahi Linux / Apple Silicon |
| `darwin` | `github:nix-darwin/nix-darwin` | macOS system configuration |
| `nix-homebrew` | `github:zhaofengli/nix-homebrew` | Declarative Homebrew (macOS) |
| `stylix` | `github:nix-community/stylix` | System-wide theming |
| `nix-vscode-extensions` | `github:nix-community/nix-vscode-extensions` | VS Code extension packages |
| `authentik-nix` | `github:nix-community/authentik-nix` | Authentik SSO |
| `nix-cachyos-kernel` | `github:xddxdd/nix-cachyos-kernel` | CachyOS optimised kernels |
| `lsfg-vk` | `github:pabloaul/lsfg-vk-flake` | Lossless Scaling frame generation (Linux) |
| `nix-index-database` | `github:nix-community/nix-index-database` | Pre-built nix-index database |
| `steam-rom-manager` | `github:mjallen18/nix-steam-rom-manager` | Steam ROM Manager package |
| `nix-plist-manager` | `github:sushydev/nix-plist-manager` | macOS plist management |
| `nix-rosetta-builder` | `github:cpick/nix-rosetta-builder` | Rosetta build support (macOS) |
| `pre-commit-hooks-nix` | `github:cachix/pre-commit-hooks.nix` | Pre-commit hooks |
| `treefmt-nix` | `github:numtide/treefmt-nix` | Code formatting |

`nixpkgs` and `home-manager` are aliases pointing to the unstable variants.

## Module System

### Structure

All modules follow a standard Snowfall Lib pattern and are automatically discovered. Each module exposes options under the `mjallen` namespace:

```nix
# Enable a module
mjallen.services.jellyfin.enable = true;
mjallen.desktop.gnome.enable = true;
mjallen.hardware.amd.enable = true;
```

### `mkModule` helper

Most service modules are built with `lib.mjallen.mkModule` (`lib/module/default.nix`), which provides a standard set of options:

| Option | Default | Description |
|---|---|---|
| `enable` | `false` | Enable/disable the module |
| `port` | `80` | Service listen port |
| `listenAddress` | `"0.0.0.0"` | Bind address |
| `openFirewall` | `true` | Open firewall ports |
| `configDir` | `/var/lib/<name>` | Config directory |
| `dataDir` | `/var/lib/<name>/data` | Data directory |
| `createUser` | `false` | Create a dedicated system user |
| `configureDb` | `false` | Create a PostgreSQL database |
| `environmentFile` | `null` | Path to an env-file |
| `reverseProxy.enable` | `false` | Add a Caddy reverse proxy block |
| `reverseProxy.subdomain` | `<name>` | Caddy subdomain |
| `redis.enable` | `false` | Create a dedicated Redis instance |

### NixOS modules (`modules/nixos/`)

| Category | Paths | Description |
|---|---|---|
| Boot | `boot/common/`, `boot/lanzaboote/`, `boot/plymouth/`, `boot/systemd-boot/` | Bootloader configurations |
| Desktop | `desktop/gnome/`, `desktop/hyprland/`, `desktop/cosmic/` | Desktop environments |
| Development | `development/` | Dev tools, language support, containers |
| Hardware | `hardware/amd/`, `hardware/nvidia/`, `hardware/battery/`, `hardware/raspberry-pi/`, `hardware/openrgb/`, ... | Hardware-specific configs |
| Headless | `headless/` | Headless server profile (watchdog, no suspend) |
| Home Assistant | `homeassistant/` | Smart home automation suite |
| Impermanence | `impermanence/` | Ephemeral root + persistent state |
| Monitoring | `monitoring/` | Prometheus/Grafana metrics |
| Network | `network/` | Hostname, firewall, NetworkManager, static IP |
| Power | `power/` | UPS support |
| Programs | `programs/` | System-wide programs (nix-index, gnupg, etc.) |
| Security | `security/common/`, `security/tpm/` | Common hardening, TPM unlock |
| Services | `services/<name>/` | ~50 self-hosted service modules (see below) |
| SOPS | `sops/` | Secret management setup |
| System | `system/` | Miscellaneous system settings |
| User | `user/` | User account management |
| Virtualization | `virtualization/` | libvirt, containers |

### Home Manager modules (`modules/home/`)

| Category | Paths | Description |
|---|---|---|
| Desktop | `desktop/gnome/`, `desktop/theme/` | GNOME and theming |
| GPG | `gpg/` | GPG agent configuration |
| Programs | `programs/btop/`, `programs/git/`, `programs/zsh/`, `programs/kitty/`, `programs/waybar/`, `programs/hyprland/`, `programs/wofi/`, `programs/mako/`, `programs/wlogout/`, `programs/librewolf/`, `programs/opencode/`, `programs/update-checker/`, ... | User applications |
| Services | `services/pass/` | Password store integration |
| Shell | `shell-aliases/` | Common shell aliases |
| SOPS | `sops/` | User-level secret integration |
| Stylix | `stylix/` | System-wide theming |
| User | `user/` | User environment defaults |

## Secrets Management

Secrets are encrypted with [SOPS](https://github.com/getsops/sops) using age keys derived from each machine's SSH host key (`/etc/ssh/ssh_host_ed25519_key`). The `.sops.yaml` file maps secret file path patterns to the set of age recipients that can decrypt them.

Each host has its own secrets file:

| File | Host |
|---|---|
| `secrets/secrets.yaml` | Shared (all hosts) |
| `secrets/nas-secrets.yaml` | jallen-nas |
| `secrets/pi5-secrets.yaml` | pi5 |
| `secrets/allyx-secrets.yaml` | allyx |
| `secrets/nuc-secrets.yaml` | nuc-nixos |
| `secrets/mac-secrets.yaml` | macbook-pro-nixos |
| `secrets/desktop-secrets.yaml` | matt-nixos |

See the [Secrets Management](../README.md#secrets-management) section of the root README for full details on generating keys and adding secrets.

## Deployment

```bash
# NixOS system
sudo nixos-rebuild switch --flake .#hostname

# macOS (nix-darwin)
darwin-rebuild switch --flake .#hostname

# Home Manager only
home-manager switch --flake .#username@hostname
```