Architecture - Ziad0dev/dots GitHub Wiki

flake.nix       inputs, username, every output
lib/            mk.nix (output builders), overlays, shared systemd hardening, nvidia fix
hosts/          nixos/ (the desktop), darwin/
modules/        NixOS modules, one concern per file
home/           home-manager: home.nix dispatcher, profiles/, one module per app
config/         raw app config, symlinked live into ~/.config
config/themes/  palettes + templates rendered by themectl
flakes/         standalone tool flakes (infosec, maths), also imported as HM modules
templates/      `nix flake init` templates
scripts/        shell sources packaged by the nix modules, plus the git hook

Supported systems: x86_64-linux, aarch64-linux, aarch64-darwin (nixpkgs 26.11 dropped x86_64-darwin).

Three builders, all passing the same specialArgs — inputs, username, hostname, system, profile — so every module can take them as arguments.

mk.nixos  { hostname, username, system ? "x86_64-linux", profile ? "desktop", modules ? [ ], homeModule ? ../home/home.nix, home ? true }
mk.darwin { hostname, username, system ? "aarch64-darwin", profile ? "desktop", modules ? [ ], homeModule ? ../home/home.nix }
mk.home   { name, username, system, profile ? "minimal", repoPath ? null, homeDirectory ? null, modules ? [ ] }

When home-manager rides on a system (mk.nixos, mk.darwin) it runs with useGlobalPkgs, useUserPackages, backupFileExtension = "backup" and overwriteBackup (a second clash on the same file replaces the old .backup instead of failing the activation). There is no separate home-manager switch on the desktop — one nh os switch activates both, and one rollback reverts both.

mk.home imports nixpkgs itself (mkPkgs) with allowUnfree and lib/overlays.nix.

Every input that has a nixpkgs input follows ours; duplicates are what drag in a second or third nixpkgs.

home/home.nix is only a dispatcher:

Everything under home/ that isn't a profile is an app module imported by one of these.

{ dotsLink, ... }:
{ home.file.".config/hypr".source = dotsLink "hypr"; }

dotsLink is a module argument set in profiles/base.nix. What it returns depends on dots.liveConfig:

Pure mode is what the vm host uses, and what to pick on a machine you deploy to rather than edit on. Configs are read-only there, so apps that write into their own config dir (btop saving btop.conf, lazy.nvim's lazy-lock.json) can't persist those writes.

Either way home-manager doesn't know the contents of a linked directory — so each config path has exactly one owner: either a dotsLink or an HM module, never both.

Files linked to ~/.local/state/dots/theme/* instead of config/ (btop theme, yazi theme, swayosd css) are themectl output — see Theming.

dots.repoPath is the git checkout. Declared twice, in two namespaces, both defaulting to ~/dots:

• NixOS: modules/quality.nix — used by programs.nh.flake.
• home-manager: home/profiles/base.nix — used by dotsLink in live mode, the flakeup abbrev, git hooks, standalone programs.nh.flake, and baked into the scripts that act on the checkout (dots-update, dots-updates, dots-timemachine; each still honours DOTS_REPO / DOTS_DIR).

dots.src (home-manager, read-only) is where config/ is read from at runtime: repoPath in live mode, a store copy of just config/ in pure mode (so unrelated repo edits don't rebuild it). themectl's palettes and templates, fastfetch art and the theme pickers (DOTS_DIR in the Quickshell unit) use it. Scripts under config/quickshell/rise/scripts are reached through ~/.config/quickshell/rise, which is right in both modes.

How rebuild abbrevs are chosen: update is nh os switch when home-manager rides on this NixOS host, nh darwin switch on nix-darwin, and nh home switch -c <output> for a standalone homeConfigurations output (mk.home passes its attribute name). Off NixOS, home-manager installs nh itself.

The functions here are not modules: keep them out of modules/ (everything there is imported) and out of imports unless called first, or NixOS calls them with module arguments.

_{Source: docs/architecture.md}