0017 NixOS module layering with profiles

0017 NixOS module layering with profiles#

Context and Problem Statement#

NixOS modules in business-operations need to be organized for reuse. Users have different needs:

  • Some want fine-grained control, picking individual modules

  • Some want sensible defaults without understanding every detail

How should modules be structured to serve both use cases?

Considered Options#

  1. Flat modules only - Every module is independent, users compose them manually

  2. Monolithic profiles only - Pre-composed configurations, take-it-or-leave-it

  3. Layered approach - Tiny focused modules + profiles that compose them

Decision Outcome#

Use a layered approach with two levels:

Tiny modules (nixos/modules/) - Single-purpose, focused configurations:

nixos/modules/
  nix/
    flakes.nix      # Just experimental-features for flakes
    gc.nix          # Garbage collection settings
  ...

Profiles (nixos/profiles/) - Compose modules into common patterns:

nixos/profiles/
  base.nix          # imports [ ../modules/nix/flakes.nix ... ]

This gives users control when needed while providing convenience for common cases. Profiles are optional - users can always import individual modules directly.

Start with tiny modules only. Add profiles when there are 3+ modules worth composing.