Project architecture

The framework is organized in layers: each level serves the one above, from the base system up to host and user profiles.

File organization

The complete structure and abstraction layers are described in the project overview.

• dnf/ : the framework : modules, Home Manager configuration, libraries.
• usr/ : the local project (writable) : configuration, secrets, machines.
• var/generated/ : generated files (do not edit by hand).
• src/generator/ : generator sources (Rust).
• doc/ : this documentation.

Reference modules

The ready-to-use modules are documented in the module reference, sorted by category (system, service, security, console, graphic, admin, user, mixin, home).

Abstraction layers

Each level builds upon the previous one: the base system serves the modules, which compose the profiles, which define hosts and users.

• Complete file structure : detailed directory tree.
• Layer diagram : from system to profiles.

Layer	Where	Role
Modules	dnf/modules/standard/	Unit bricks (a service, a system setting).
Mixins	dnf/modules/mixin/	Macro-modules : host profiles, profile complements.
Home	dnf/home/	Home Manager 🡕 modules and profiles (users).
Library	dnf/lib/	Shared helpers (dnfLib) : network, OIDC, firewall, security…
Generation	src/generator/	Transforms etc/config.yaml → var/generated/.

Framework vs local project

The framework (dnf/) is reusable and rarely changed; the project (usr/) overrides it without touching it.

• usr/modules/ mirrors dnf/modules/: a file at the same path overrides or complements the framework module.
• usr/home/ mirrors dnf/home/ for user profiles and modules.
• usr/machines/<host>/ holds hardware (hardware-configuration.nix, disko.nix) and specific settings.
• usr/secrets/ contains encrypted secrets (sops).

Golden rule

Edit dnf/ to evolve the framework (useful to everyone), usr/ to adapt a specific network. Never edit var/generated/.

Arguments injected into modules

DNF modules receive, in addition to standard NixOS arguments, specific arguments via specialArgs (the generator and flake.nix provide them):

Argument	Content
config, lib, pkgs	Standard NixOS arguments.
dnfLib	Shared DNF helpers (see Modules).
dnfConfig	Global configuration (network ports, default values).
host	The current host: hostname, users, services, features, profile.
hosts	The list of all hosts on the network.
network	Network topology: zones, domain, services.
zone	The current host’s zone.
workDir	Project root (absolute paths).

Accuracy

The exact list of arguments for a module is visible at the top of its file (the { lib, config, dnfLib, host, ... } block). When in doubt, check the source.

Generated overlays

Some values don’t belong in etc/config.yaml (manual): too technical, or provisioned by a tool. The pattern: a script writes a var/generated/<x>.nix file that the assembler dnf/lib/mk-configuration.nix merges into an injected argument.

Example: just configure-alert-bot writes var/generated/matrix.nix (alert bot identity + room IDs), merged into network.matrix.* via recursiveUpdate (the generated file wins). Modules read network.matrix without knowing where it comes from.

When to use

For derived or provisioned data, never edited by hand, outside of config.yaml. The overlay is optional: if absent, the argument keeps its base value.