How repparw/nix works
1. This repo is a Nix Flake-based NixOS configuration, not an application codebase. The architecture is a layered module system that assembles complete machine configurations for two hosts: alpha (desktop) and beta (laptop).
2. The top-level build boundary is the flake: flake.nix plus flake.lock define the package set, module inputs, and outputs. Supporting repo tooling is also flake-managed via treefmt.toml, modules/checks.nix, and modules/git-hooks.nix.
3. Host-specific configuration lives in modules/hosts/alpha.nix and modules/hosts/beta.nix. These are the machine entrypoints that combine shared modules with per-device choices like hardware, display, networking, and enabled services.
4. Shared system behavior is split into general-purpose modules under modules/aspects/ and lower-level defaults under modules/defaults.nix, modules/nix.nix, modules/nixpkgs.nix, modules/system.nix, and modules/networking.nix. This is the main reuse boundary: common policy is defined once and then selectively composed into each host.
5. The “aspects” directory represents feature bundles rather than individual packages. There are explicit bundles for CLI workflows, GUI/desktop workflows, gaming, streaming, secrets, timers, virtualization, auto-upgrades, Nix tooling, and editor integration. That makes the system architecture additive: hosts are built by enabling a set of capabilities.
6. The desktop stack is centered around niri and related modules such as modules/aspects/niri.nix, gui/wm.nix, gui/kanshi.nix, and gui/logid.nix. Additional GUI apps are grouped under gui/apps.nix, browser.nix, mpv.nix, obs.nix, spotify.nix, and zathura.nix, indicating a full interactive workstation layer.
7. The CLI/admin layer is similarly bundled: shell, SSH, Git, tmux, task management, editors, file manager, and rclone live under modules/aspects/cli/. This is the primary operator interface for machine management and remote administration.
8. Self-hosted services are isolated under modules/_services/. These include media and content services (jellyfin, freshrss, paperless), notification and monitoring utilities (ntfy, changedetection, dozzle), and authentication/reverse-proxy infrastructure (authelia, proxy). This is the main service boundary between the host OS and network-facing workloads.
9. Secrets are handled separately from normal config. modules/aspects/secrets.nix and secrets.yaml indicate encrypted secret material managed outside the plain Nix expressions, likely through sops-nix as noted in the README. That keeps credentials out of the declarative host modules while still allowing them to be wired into services.
10. There is explicit support for validation and safe iteration. modules/vm.nix, modules/aspects/virtualisation.nix, and the README’s vmAlpha/vmBeta targets show that each host can be built and exercised in a VM before deployment. That creates a clear test boundary around the full system configuration.
11. A few modules suggest targeted integrations and hardware-specific concerns, such as mercusys-ma530.nix, dendritic.nix, repparw.nix, and virtual-display.nix. These are narrow adapters that sit at the edge of the system, likely for specific devices or workflows rather than core platform behavior.
12. Overall, the diagram should show a layered NixOS composition: flake inputs at the top, shared baseline modules in the middle, host-specific assembly at the bottom, and feature/service subtrees branching off for desktop, CLI, secrets, virtualization, and network-facing services.
Main entry points: defaults.nix Defaults · flake.nix Flake · services.nix Services · alpha.nix Alpha
Components 22
Build & tooling
Flake boundary and repository-level validation/tooling.
- Flake · Top-level Nix flake defining inputs and outputs.
flake.nix - Lockfile · Pinned input revisions for the flake.
flake.lock - Checks · Repository validation and CI-style checks.
modules/checks.nix - Git hooks · Pre-commit and repository hygiene hooks.
modules/git-hooks.nix - Formatter · Formatting rules for repo-wide tooling.
treefmt.toml
Shared base
Common NixOS policy and defaults reused by all hosts.
- Defaults · Common system defaults shared across hosts.
modules/defaults.nix - Nix · Core Nix language and daemon settings.
modules/aspects/nix.nix - Nixpkgs · Package set selection and policy.
modules/aspects/nixpkgs.nix - System · Core operating-system configuration.
modules/aspects/system.nix - Networking · Host networking and connectivity defaults.
modules/aspects/networking.nix
Feature bundles
Composable capability modules enabled per host.
- CLI · Shell, SSH, Git, tmux, tasks, editors, and file tools.
modules/aspects/cli/default.nix - GUI · Desktop session, apps, and peripheral integrations.
modules/aspects/gui/default.nix - Niri · Wayland compositor and desktop session integration.
modules/aspects/niri.nix - Streaming · Capture and streaming helpers for gaming and media use.
modules/aspects/streaming/default.nix - Virtualisation · VM support and host virtualization enablement.
modules/aspects/virtualisation.nix - Secrets · Encrypted secret wiring for modules and services.
modules/aspects/secrets.nix - Services · Shared service layer that assembles self-hosted modules.
modules/aspects/services.nix
Hosts
Machine entrypoints for alpha and beta.
Services
Self-hosted and network-facing service modules.
Connections 24
- Flake → Lockfile: pins · The flake is tied to exact input revisions.
- Flake → Checks: includes · Flake outputs include validation and checks.
- Flake → Git hooks: includes · Developer tooling is managed from the flake.
- Flake → Formatter: formats · The repository formatting contract lives alongside the flake.
- Flake → Defaults: imports · Hosts are assembled from shared baseline modules.
- Defaults → Nix: layers · Baseline config composes Nix policy.
- Defaults → Nixpkgs: layers · Baseline config composes package-set policy.
- Defaults → System: layers · Baseline config composes system policy.
- Defaults → Networking: layers · Baseline config composes networking policy.
- Defaults → CLI: enables · Common operator tooling is available to hosts.
- Defaults → Secrets: enables · Shared secrets integration is available to hosts.
- Alpha → GUI: uses · Desktop host enables the GUI bundle.
- Alpha → CLI: uses · Desktop host also uses the CLI bundle.
- Alpha → Virtualisation: uses · Desktop host supports VM-based validation.
- Alpha → Services: uses · Desktop host can include self-hosted services.
- Beta → CLI: uses · Laptop host is built around the CLI bundle.
- Beta → Niri: uses · Laptop host uses the desktop session stack.
- Beta → Virtualisation: uses · Laptop host supports VM-based validation.
- GUI → Niri: contains · The GUI bundle centers on the Niri desktop stack.
- GUI → Streaming: contains · Desktop bundle includes streaming and media workflows.
- Services → Proxy: assembles · Shared service layer wires proxy/auth boundary.
- Services → Media: assembles · Shared service layer wires media services.
- Services → Ops tools: assembles · Shared service layer wires operational services.
- Services → Secrets: depends on · Services consume encrypted secret material.