# 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.

## Directory Structure

```
.
├── checks/                # Pre-commit hooks and other checks
├── flake.nix              # Main flake configuration
├── homes/                 # Home-manager configurations for users
│   ├── aarch64-darwin/    # macOS home configurations
│   ├── aarch64-linux/     # ARM Linux home configurations
│   └── x86_64-linux/      # x86 Linux home configurations
├── modules/               # Reusable configuration modules
│   ├── home/              # Home-manager modules
│   └── nixos/             # NixOS system modules
│       ├── boot/          # Boot configuration modules
│       ├── desktop/       # Desktop environment modules
│       ├── hardware/      # Hardware-specific modules
│       ├── homeassistant/ # Home Assistant modules
│       ├── network/       # Network configuration modules
│       ├── services/      # Service configuration modules
│       └── ...            # Other module categories
├── overlays/              # Nixpkgs overlays
├── packages/              # Custom package definitions
├── secrets/               # Encrypted secrets (managed with sops-nix)
└── systems/               # System-specific configurations
    ├── aarch64-darwin/    # macOS system configurations
    ├── aarch64-linux/     # ARM Linux system configurations
    └── x86_64-linux/      # x86 Linux system configurations
        ├── jallen-nas/    # NAS server configuration
        ├── matt-nixos/    # Desktop configuration
        ├── nuc-nixos/     # NUC configuration
        ├── pi4/           # Raspberry Pi 4 configuration
        └── ...            # Other system configurations
```

## Flake Structure

The `flake.nix` file defines the inputs (external dependencies) and outputs (configurations) of this repository:

### Inputs

- **nixpkgs-unstable**: The unstable channel of Nixpkgs
- **nixpkgs-stable**: The stable channel of Nixpkgs (25.11)
- **home-manager**: User environment management
- **snowfall-lib**: Library for structuring flake repositories
- **impermanence**: Persistent state management
- **lanzaboote**: Secure boot implementation
- **nixos-hardware**: Hardware-specific configurations
- **sops-nix**: Secret management
- **disko**: Disk partitioning and formatting
- **And more specialized inputs**

### Outputs

The outputs are generated using Snowfall Lib's `mkFlake` function, which automatically discovers and assembles:

- **NixOS system configurations**: For each system in the `systems/` directory
- **Home Manager configurations**: For each configuration in the `homes/` directory
- **Packages**: From the `packages/` directory
- **Modules**: From the `modules/` directory
- **Overlays**: From the `overlays/` directory

## Module System

The module system uses a modular approach where:

1. **Common modules** are defined in `modules/nixos/` and `modules/home/`
2. **System-specific modules** are defined in `systems/<architecture>/<hostname>/`

Each module follows the NixOS module pattern, with:
- `default.nix`: Main module implementation
- `options.nix`: Option declarations

## Integration with Snowfall Lib

Snowfall Lib provides:
1. **Automatic discovery** of modules, overlays, and packages
2. **Consistent structure** across the repository
3. **Common utilities** for working with flakes

## Secrets Management

Secrets are managed using [sops-nix](https://github.com/Mic92/sops-nix), with:
- Encrypted secret files in the `secrets/` directory
- `.sops.yaml` configuration file in the root
- Key management integrated into the configuration

## Deployment Process

Systems are built and deployed using:
```bash
nixos-rebuild switch --flake .#hostname
```

This command:
1. Evaluates the flake for the specified hostname
2. Builds the resulting configuration
3. Activates it on the current system