# repparw/nix architecture

> Architecture diagram of the GitHub repository repparw/nix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/repparw/nix
- Repository: https://github.com/repparw/nix

## Overview

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: [`modules/defaults.nix`](https://github.com/repparw/nix/blob/main/modules/defaults.nix) (Defaults), [`flake.nix`](https://github.com/repparw/nix/blob/main/flake.nix) (Flake), [`modules/aspects/services.nix`](https://github.com/repparw/nix/blob/main/modules/aspects/services.nix) (Services), [`modules/hosts/alpha.nix`](https://github.com/repparw/nix/blob/main/modules/hosts/alpha.nix) (Alpha)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build & tooling"]
  node_flake["Flake<br/>[flake.nix]"]
  node_lock["Lockfile<br/>dependency lock<br/>[flake.lock]"]
  node_checks["Checks<br/>validation<br/>[checks.nix]"]
  node_hooks["Git hooks<br/>dev tooling<br/>[git-hooks.nix]"]
  node_treefmt["Formatter<br/>format config<br/>[treefmt.toml]"]
end

subgraph group_shared["Shared base"]
  node_defaults["Defaults<br/>baseline module<br/>[defaults.nix]"]
  node_nixcfg["Nix<br/>language policy<br/>[nix.nix]"]
  node_nixpkgs["Nixpkgs<br/>package policy<br/>[nixpkgs.nix]"]
  node_system["System<br/>os policy<br/>[system.nix]"]
  node_networking["Networking<br/>network policy<br/>[networking.nix]"]
end

subgraph group_aspects["Feature bundles"]
  node_cli["CLI<br/>operator bundle<br/>[default.nix]"]
  node_gui["GUI<br/>desktop bundle<br/>[default.nix]"]
  node_niri["Niri<br/>wayland session<br/>[niri.nix]"]
  node_streaming["Streaming<br/>media workflow<br/>[default.nix]"]
  node_virtualisation["Virtualisation<br/>vm workflow<br/>[virtualisation.nix]"]
  node_secrets["Secrets<br/>secret handling<br/>[secrets.nix]"]
  node_servicesmod["Services<br/>service wiring<br/>[services.nix]"]
end

subgraph group_hosts["Hosts"]
  node_alpha["Alpha<br/>desktop host<br/>[alpha.nix]"]
  node_beta["Beta<br/>laptop host<br/>[beta.nix]"]
end

subgraph group_services["Services"]
  node_svcproxy["Proxy<br/>[proxy.nix]"]
  node_svcmedia["Media<br/>[jellyfin.nix]"]
  node_svcops["Ops tools<br/>ops services<br/>[dozzle.nix]"]
end

node_flake -->|"pins"| node_lock
node_flake -->|"includes"| node_checks
node_flake -->|"includes"| node_hooks
node_flake -->|"formats"| node_treefmt
node_flake -->|"imports"| node_defaults
node_defaults -->|"layers"| node_nixcfg
node_defaults -->|"layers"| node_nixpkgs
node_defaults -->|"layers"| node_system
node_defaults -->|"layers"| node_networking
node_defaults -->|"enables"| node_cli
node_defaults -->|"enables"| node_secrets
node_alpha -->|"uses"| node_gui
node_alpha -->|"uses"| node_cli
node_alpha -->|"uses"| node_virtualisation
node_alpha -->|"uses"| node_servicesmod
node_beta -->|"uses"| node_cli
node_beta -->|"uses"| node_niri
node_beta -->|"uses"| node_virtualisation
node_gui -->|"contains"| node_niri
node_gui -->|"contains"| node_streaming
node_servicesmod -->|"assembles"| node_svcproxy
node_servicesmod -->|"assembles"| node_svcmedia
node_servicesmod -->|"assembles"| node_svcops
node_servicesmod -->|"depends on"| node_secrets

click node_flake "https://github.com/repparw/nix/blob/main/flake.nix"
click node_lock "https://github.com/repparw/nix/blob/main/flake.lock"
click node_checks "https://github.com/repparw/nix/blob/main/modules/checks.nix"
click node_hooks "https://github.com/repparw/nix/blob/main/modules/git-hooks.nix"
click node_treefmt "https://github.com/repparw/nix/blob/main/treefmt.toml"
click node_defaults "https://github.com/repparw/nix/blob/main/modules/defaults.nix"
click node_nixcfg "https://github.com/repparw/nix/blob/main/modules/aspects/nix.nix"
click node_nixpkgs "https://github.com/repparw/nix/blob/main/modules/aspects/nixpkgs.nix"
click node_system "https://github.com/repparw/nix/blob/main/modules/aspects/system.nix"
click node_networking "https://github.com/repparw/nix/blob/main/modules/aspects/networking.nix"
click node_alpha "https://github.com/repparw/nix/blob/main/modules/hosts/alpha.nix"
click node_beta "https://github.com/repparw/nix/blob/main/modules/hosts/beta.nix"
click node_cli "https://github.com/repparw/nix/blob/main/modules/aspects/cli/default.nix"
click node_gui "https://github.com/repparw/nix/blob/main/modules/aspects/gui/default.nix"
click node_niri "https://github.com/repparw/nix/blob/main/modules/aspects/niri.nix"
click node_streaming "https://github.com/repparw/nix/blob/main/modules/aspects/streaming/default.nix"
click node_virtualisation "https://github.com/repparw/nix/blob/main/modules/aspects/virtualisation.nix"
click node_secrets "https://github.com/repparw/nix/blob/main/modules/aspects/secrets.nix"
click node_servicesmod "https://github.com/repparw/nix/blob/main/modules/aspects/services.nix"
click node_svcproxy "https://github.com/repparw/nix/blob/main/modules/_services/proxy.nix"
click node_svcmedia "https://github.com/repparw/nix/blob/main/modules/_services/jellyfin.nix"
click node_svcops "https://github.com/repparw/nix/blob/main/modules/_services/dozzle.nix"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flake,node_lock,node_checks,node_hooks,node_treefmt toneBlue
class node_defaults,node_nixcfg,node_nixpkgs,node_system,node_networking toneAmber
class node_cli,node_gui,node_niri,node_streaming,node_virtualisation,node_secrets,node_servicesmod toneMint
class node_alpha,node_beta toneRose
class node_svcproxy,node_svcmedia,node_svcops toneIndigo
```

## Components

### Build & tooling

Flake boundary and repository-level validation/tooling.

- [Flake](https://github.com/repparw/nix/blob/main/flake.nix): flake · Top-level Nix flake defining inputs and outputs. · `flake.nix`
- [Lockfile](https://github.com/repparw/nix/blob/main/flake.lock): dependency lock · Pinned input revisions for the flake. · `flake.lock`
- [Checks](https://github.com/repparw/nix/blob/main/modules/checks.nix): validation · Repository validation and CI-style checks. · `modules/checks.nix`
- [Git hooks](https://github.com/repparw/nix/blob/main/modules/git-hooks.nix): dev tooling · Pre-commit and repository hygiene hooks. · `modules/git-hooks.nix`
- [Formatter](https://github.com/repparw/nix/blob/main/treefmt.toml): format config · Formatting rules for repo-wide tooling. · `treefmt.toml`

### Shared base

Common NixOS policy and defaults reused by all hosts.

- [Defaults](https://github.com/repparw/nix/blob/main/modules/defaults.nix): baseline module · Common system defaults shared across hosts. · `modules/defaults.nix`
- [Nix](https://github.com/repparw/nix/blob/main/modules/aspects/nix.nix): language policy · Core Nix language and daemon settings. · `modules/aspects/nix.nix`
- [Nixpkgs](https://github.com/repparw/nix/blob/main/modules/aspects/nixpkgs.nix): package policy · Package set selection and policy. · `modules/aspects/nixpkgs.nix`
- [System](https://github.com/repparw/nix/blob/main/modules/aspects/system.nix): os policy · Core operating-system configuration. · `modules/aspects/system.nix`
- [Networking](https://github.com/repparw/nix/blob/main/modules/aspects/networking.nix): network policy · Host networking and connectivity defaults. · `modules/aspects/networking.nix`

### Feature bundles

Composable capability modules enabled per host.

- [CLI](https://github.com/repparw/nix/blob/main/modules/aspects/cli/default.nix): operator bundle · Shell, SSH, Git, tmux, tasks, editors, and file tools. · `modules/aspects/cli/default.nix`
- [GUI](https://github.com/repparw/nix/blob/main/modules/aspects/gui/default.nix): desktop bundle · Desktop session, apps, and peripheral integrations. · `modules/aspects/gui/default.nix`
- [Niri](https://github.com/repparw/nix/blob/main/modules/aspects/niri.nix): wayland session · Wayland compositor and desktop session integration. · `modules/aspects/niri.nix`
- [Streaming](https://github.com/repparw/nix/blob/main/modules/aspects/streaming/default.nix): media workflow · Capture and streaming helpers for gaming and media use. · `modules/aspects/streaming/default.nix`
- [Virtualisation](https://github.com/repparw/nix/blob/main/modules/aspects/virtualisation.nix): vm workflow · VM support and host virtualization enablement. · `modules/aspects/virtualisation.nix`
- [Secrets](https://github.com/repparw/nix/blob/main/modules/aspects/secrets.nix): secret handling · Encrypted secret wiring for modules and services. · `modules/aspects/secrets.nix`
- [Services](https://github.com/repparw/nix/blob/main/modules/aspects/services.nix): service wiring · Shared service layer that assembles self-hosted modules. · `modules/aspects/services.nix`

### Hosts

Machine entrypoints for alpha and beta.

- [Alpha](https://github.com/repparw/nix/blob/main/modules/hosts/alpha.nix): desktop host · Desktop machine entrypoint and host composition. · `modules/hosts/alpha.nix`
- [Beta](https://github.com/repparw/nix/blob/main/modules/hosts/beta.nix): laptop host · Laptop machine entrypoint and host composition. · `modules/hosts/beta.nix`

### Services

Self-hosted and network-facing service modules.

- [Proxy](https://github.com/repparw/nix/blob/main/modules/_services/proxy.nix): reverse proxy · Authentication and reverse-proxy boundary. · `modules/_services/proxy.nix`
- [Media](https://github.com/repparw/nix/blob/main/modules/_services/jellyfin.nix): media services · Jellyfin and related media/content services. · `modules/_services/jellyfin.nix`
- [Ops tools](https://github.com/repparw/nix/blob/main/modules/_services/dozzle.nix): ops services · Monitoring, notifications, and admin helpers. · `modules/_services/dozzle.nix`

## Connections

- 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.
