Architecture

This repo starts from one pinned nixpkgs revision. For each supported system, it imports that revision and applies the same overlay stack. Packages, hosts, Home Manager, and tooling use those package sets.

For a Nix newcomer, the central idea is simple: build a consistent package universe for each platform, then reuse it across the repo.

Big Picture

flake.lock
  -> flake.nix inputs
    -> default.nix imports pinned nixpkgs
      -> overlays.nix
        -> mods/*
          -> pkgs/*
      -> home.nix
      -> hosts/*
        -> hosts/modules/*
      -> scripts.nix / pog / hex / snowball

Pinned Base

• flake.lock pins the upstream inputs.
• flake.nix defines the public outputs for packages, hosts, dev shells, and generators.
• default.nix imports flake.inputs.nixpkgs, injects shared inputs like pog, hex, uv2nix, and poetry2nix, then applies local overlays.

The flake creates one package set per supported system from the same pin and overlay stack, then reuses each set across its outputs.

Why Both flake.nix And default.nix Exist

This is a common point of confusion for new readers.

• flake.nix is the public front door. It declares inputs and publishes outputs such as packages, hosts, dev shells, and helper scripts.
• default.nix is the package-set constructor. It imports the pinned nixpkgs, injects shared inputs, and applies local overlays to produce the pkgs set the rest of the repo consumes.

You can read the repo as "the flake exposes things, default.nix builds the shared package universe those things are made from."

One Important Definition

An overlay is just a function that receives a package set and returns additions or changes to it. In this repo, overlays are how local packages, helper abstractions, and repo-specific tools become first-class parts of pkgs.

Local Overlays

• overlays.nix is the ordered list of local overlays.
• mods/_pkgs.nix recursively imports pkgs/* and exposes those derivations at the top level.
• mods/pkgs/ adds higher-level package families and composed outputs.
• mods/final.nix is the last pass for final assembly, formatter setup, and selected overrides.

flake.nix publishes supported, non-broken derivations discovered under pkgs/ as packages, which keeps flake validation focused on repository-owned package definitions. The complete overlayed package universe remains under legacyPackages, so ordinary installables still resolve through the standard flake fallback. The structural overlay manifest lives at lib.overlayDelta.<system> and can be inspected with overlay-diff or built selectively with overlay-check.

User and Machine Layers

• home.nix is the main Home Manager entry point for the user environment.
• hosts/<name>/configuration.nix contains per-machine system configuration.
• hosts/common.nix and hosts/common_darwin.nix hold shared defaults.
• hosts/modules/* contains reusable service and configuration modules that hosts import as needed.

Host Architecture

• hosts/constants.nix defines host names, machine groups, and shared constants.
• NixOS and nix-darwin hosts live in the same repo.
• Shared modules are grouped by concern, such as conf, darwin, exporters, games, and servers.

Tooling Surfaces

• mods/pog/* defines many repo-local CLI wrappers built with pog.
• mods/hms.nix exposes hms and hmx.<host> switch helpers.
• scripts.nix exposes checked script outputs under .#scripts.*.
• mods/snowball.nix packages targeted service bundles for machines that are not managed as full hosts.

Why This Layout Works

• The same overlayed package set is reused by home.nix, host configs, and flake outputs.
• New packages can be added under pkgs/* without inventing a second packaging path.
• High-level tools like pog and hex can be part of the same package universe as the systems they support.
• Readers can choose the right level: curated guide pages first, generated reference indexes second.