# daniel-w-innes/nixos architecture

> Architecture diagram of the GitHub repository daniel-w-innes/nixos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/daniel-w-innes/nixos
- Repository: https://github.com/daniel-w-innes/nixos

## Overview

#### Purpose and entry points
This is a Nix flake repository for declarative management of multiple NixOS machines, user environments, self-hosted services, secrets, and custom monitoring exporters. Primary evaluation/deployment entry points are `flake.nix`, host definitions under `hosts/`, and reusable system modules under `generic/` and `modules/`.

#### Host composition
Each machine has a dedicated NixOS configuration plus hardware/facter inputs:
- `hosts/cucamelon/configuration.nix`
- `hosts/melon/configuration.nix`
- `hosts/onion/configuration.nix`

Host configurations are the composition boundary: they select common profiles, machine-specific hardware, service roles, and secrets. `hardware-configuration.nix` and `facter.json` represent host hardware discovery rather than shared policy.

#### Reusable system profiles
`generic/` contains composable NixOS role and capability modules. These divide hosts into desktop, laptop, minimal, server, networking, remote access, upgrades, and observability concerns:
- `generic/desktop.nix`
- `generic/server.nix`
- `generic/autoUpgrade.nix`

Service-host aggregation is centered on `generic/server/all.nix`, with individual service modules separated so hosts can enable a selected service set.

#### Self-hosted service platform
The server layer configures a homelab-style application stack, including Forgejo, media/library services, search, file sharing, and download automation:
- `generic/server/forgejo.nix`
- `generic/server/arr.nix`
- `generic/server/immich.nix`

Ingress is separated from applications through Traefik configuration and target/dynamic-routing modules:
- `generic/server/traefik.nix`
- `generic/server/traefik-dynamic.nix`
- `generic/server/traefik-targets.nix`

This establishes a boundary between externally exposed routing and backend service definitions. Other material external services include Meilisearch, Searx, SMB, Calibre, Dawarich, BookOrbit, and weather integrations.

#### User environment and graphical sessions
Home Manager-style user configuration is organized independently from system modules. Base, terminal, GUI, desktop, laptop, and server profiles are composed with multiple Wayland compositor configurations:
- `home/base.nix`
- `home/desktop.nix`
- `home/hypr.nix`

Compositor-specific runtime configuration is maintained as native config assets, e.g. `home/hyprland/hyprland.conf`, `home/niri/config.kdl`, and `home/sway/config`. Waybar configuration is scoped per compositor.

#### Monitoring and custom Go exporters
Monitoring configuration is split between generic Prometheus enablement and custom Nix-packaged exporters:
- `generic/prometheus.nix`
- `modules/airzone-exporter.nix`
- `modules/konnected-exporter.nix`

The exporters are Go programs with independent module definitions, such as `modules/airzone-exporter/main.go` and `modules/openweathermap-exporter/main.go`. The Konnected exporter includes a checked-in Gotify API client, creating an integration boundary with Gotify; secrets also indicate InfluxDB and Grafana integrations.

#### Secret handling and automation
Encrypted age secrets are stored in `secrets/` and are consumed by service/system modules without plaintext credentials in the repository:
- `secrets/secrets.nix`
- `secrets/traefik-env.age`
- `secrets/forgejo-db-password.age`

Secret coverage includes service database/admin credentials, API keys, network credentials, VPN configuration, and exporter tokens. Forgejo CI workflows in `.forgejo/workflows/test.yml` and `.forgejo/workflows/update.yml` provide repository automation; the flake lockfile pins the Nix dependency graph in `flake.lock`.

Main entry points: [`hosts/cucamelon/configuration.nix`](https://github.com/daniel-w-innes/nixos/blob/master/hosts/cucamelon/configuration.nix) (Host configurations), [`generic/server/all.nix`](https://github.com/daniel-w-innes/nixos/blob/master/generic/server/all.nix) (Server service set), [`secrets/traefik-env.age`](https://github.com/daniel-w-innes/nixos/blob/master/secrets/traefik-env.age) (Encrypted age secrets), [`flake.nix`](https://github.com/daniel-w-innes/nixos/blob/master/flake.nix) (Flake entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_composition["Nix composition"]
  node_flake{{"Flake entry point<br/>Nix flake<br/>[flake.nix]"}}
  node_hosts["Host configurations<br/>NixOS compositions<br/>[configuration.nix]"]
  node_generic_roles["Generic role profiles<br/>NixOS modules<br/>[desktop.nix]"]
end

subgraph group_services["Service platform"]
  node_server_aggregate["Server service set<br/>NixOS module<br/>[all.nix]"]
  node_app_services["Application services<br/>NixOS modules<br/>[forgejo.nix]"]
  node_traefik{{"Traefik ingress<br/>NixOS module<br/>[traefik.nix]"}}
  node_traefik_dynamic["Dynamic routes<br/>Traefik module"]
  node_traefik_targets["Backend targets<br/>Traefik module"]
end

subgraph group_userenv["User environments"]
  node_home_profiles["Home profiles<br/>Home Manager modules<br/>[base.nix]"]
  node_compositor_profiles["Wayland profiles<br/>Home Manager modules<br/>[hypr.nix]"]
  node_compositor_assets["Compositor config assets<br/>Native configs<br/>[hyprland.conf]"]
end

subgraph group_observability["Monitoring"]
  node_prometheus["Prometheus enablement<br/>NixOS module<br/>[prometheus.nix]"]
  node_exporter_modules["Exporter modules<br/>Nix packages"]
  node_exporter_programs["Go exporter programs<br/>Go services<br/>[main.go]"]
  node_gotify_client["Gotify API client<br/>Go integration"]
end

subgraph group_automation["Secrets &amp; automation"]
  node_secret_manifest["Secret declarations<br/>Secret manifest<br/>[secrets.nix]"]
  node_encrypted_secrets["Encrypted age secrets<br/>age files<br/>[traefik-env.age]"]
  node_forgejo_workflows["Forgejo CI workflows<br/>CI automation<br/>[test.yml]"]
  node_flake_lock["Pinned dependencies<br/>Flake lockfile<br/>[flake.lock]"]
end

node_flake -->|"evaluates"| node_hosts
node_flake -->|"pins inputs"| node_flake_lock
node_hosts -->|"imports profiles"| node_generic_roles
node_hosts -->|"enables server roles"| node_server_aggregate
node_hosts -->|"composes users"| node_home_profiles
node_hosts -->|"consumes secrets"| node_secret_manifest
node_generic_roles -->|"includes server policy"| node_server_aggregate
node_server_aggregate -->|"aggregates"| node_app_services
node_server_aggregate -->|"configures ingress"| node_traefik
node_traefik -->|"loads routes"| node_traefik_dynamic
node_traefik_dynamic -->|"routes to"| node_traefik_targets
node_traefik_targets -->|"backend services"| node_app_services
node_home_profiles -->|"selects sessions"| node_compositor_profiles
node_compositor_profiles -->|"uses runtime configs"| node_compositor_assets
node_hosts -->|"enables monitoring"| node_prometheus
node_prometheus -->|"scrapes exporters"| node_exporter_modules
node_exporter_modules -->|"packages"| node_exporter_programs
node_exporter_programs -->|"Konnected integration"| node_gotify_client
node_secret_manifest -->|"declares"| node_encrypted_secrets
node_encrypted_secrets -.->|"credentials"| node_app_services
node_encrypted_secrets -.->|"tokens"| node_exporter_modules
node_forgejo_workflows -.->|"tests and updates"| node_flake

click node_flake "https://github.com/daniel-w-innes/nixos/blob/master/flake.nix"
click node_hosts "https://github.com/daniel-w-innes/nixos/blob/master/hosts/cucamelon/configuration.nix"
click node_generic_roles "https://github.com/daniel-w-innes/nixos/blob/master/generic/desktop.nix"
click node_server_aggregate "https://github.com/daniel-w-innes/nixos/blob/master/generic/server/all.nix"
click node_app_services "https://github.com/daniel-w-innes/nixos/blob/master/generic/server/forgejo.nix"
click node_traefik "https://github.com/daniel-w-innes/nixos/blob/master/generic/server/traefik.nix"
click node_traefik_dynamic "https://github.com/daniel-w-innes/nixos/blob/master/generic/server/traefik-dynamic.nix"
click node_traefik_targets "https://github.com/daniel-w-innes/nixos/blob/master/generic/server/traefik-targets.nix"
click node_home_profiles "https://github.com/daniel-w-innes/nixos/blob/master/home/base.nix"
click node_compositor_profiles "https://github.com/daniel-w-innes/nixos/blob/master/home/hypr.nix"
click node_compositor_assets "https://github.com/daniel-w-innes/nixos/blob/master/home/hyprland/hyprland.conf"
click node_prometheus "https://github.com/daniel-w-innes/nixos/blob/master/generic/prometheus.nix"
click node_exporter_modules "https://github.com/daniel-w-innes/nixos/blob/master/modules/airzone-exporter.nix"
click node_exporter_programs "https://github.com/daniel-w-innes/nixos/blob/master/modules/airzone-exporter/main.go"
click node_gotify_client "https://github.com/daniel-w-innes/nixos/blob/master/modules/konnected-exporter.nix"
click node_secret_manifest "https://github.com/daniel-w-innes/nixos/blob/master/secrets/secrets.nix"
click node_encrypted_secrets "https://github.com/daniel-w-innes/nixos/blob/master/secrets/traefik-env.age"
click node_forgejo_workflows "https://github.com/daniel-w-innes/nixos/blob/master/.forgejo/workflows/test.yml"
click node_flake_lock "https://github.com/daniel-w-innes/nixos/blob/master/flake.lock"

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_hosts,node_generic_roles toneBlue
class node_server_aggregate,node_app_services,node_traefik,node_traefik_dynamic,node_traefik_targets toneAmber
class node_home_profiles,node_compositor_profiles,node_compositor_assets toneMint
class node_prometheus,node_exporter_modules,node_exporter_programs,node_gotify_client toneRose
class node_secret_manifest,node_encrypted_secrets,node_forgejo_workflows,node_flake_lock toneIndigo
```

## Components

### Nix composition

- [Flake entry point](https://github.com/daniel-w-innes/nixos/blob/master/flake.nix): Nix flake · Evaluates machine and package outputs. · `flake.nix`
- [Host configurations](https://github.com/daniel-w-innes/nixos/blob/master/hosts/cucamelon/configuration.nix): NixOS compositions · Machine boundaries selecting profiles, hardware, roles, and secrets. · `hosts/cucamelon/configuration.nix`
- [Generic role profiles](https://github.com/daniel-w-innes/nixos/blob/master/generic/desktop.nix): NixOS modules · Composable desktop, server, upgrade, networking, and observability policy. · `generic/desktop.nix`

### Service platform

- [Server service set](https://github.com/daniel-w-innes/nixos/blob/master/generic/server/all.nix): NixOS module · Aggregates enabled homelab service modules. · `generic/server/all.nix`
- [Application services](https://github.com/daniel-w-innes/nixos/blob/master/generic/server/forgejo.nix): NixOS modules · Forgejo, media, library, search, sharing, and automation services. · `generic/server/forgejo.nix`
- [Traefik ingress](https://github.com/daniel-w-innes/nixos/blob/master/generic/server/traefik.nix): NixOS module · Separates exposed routing from application backends. · `generic/server/traefik.nix`
- [Dynamic routes](https://github.com/daniel-w-innes/nixos/blob/master/generic/server/traefik-dynamic.nix): Traefik module · `generic/server/traefik-dynamic.nix`
- [Backend targets](https://github.com/daniel-w-innes/nixos/blob/master/generic/server/traefik-targets.nix): Traefik module · `generic/server/traefik-targets.nix`

### User environments

- [Home profiles](https://github.com/daniel-w-innes/nixos/blob/master/home/base.nix): Home Manager modules · Independent base, desktop, terminal, GUI, laptop, and server user composition. · `home/base.nix`
- [Wayland profiles](https://github.com/daniel-w-innes/nixos/blob/master/home/hypr.nix): Home Manager modules · Compositor-specific user session setup. · `home/hypr.nix`
- [Compositor config assets](https://github.com/daniel-w-innes/nixos/blob/master/home/hyprland/hyprland.conf): Native configs · Runtime configuration for Hyprland, Niri, Sway, and scoped Waybar. · `home/hyprland/hyprland.conf`

### Monitoring

- [Prometheus enablement](https://github.com/daniel-w-innes/nixos/blob/master/generic/prometheus.nix): NixOS module · Configures generic monitoring integration. · `generic/prometheus.nix`
- [Exporter modules](https://github.com/daniel-w-innes/nixos/blob/master/modules/airzone-exporter.nix): Nix packages · Packages and enables custom monitoring exporters. · `modules/airzone-exporter.nix`
- [Go exporter programs](https://github.com/daniel-w-innes/nixos/blob/master/modules/airzone-exporter/main.go): Go services · Custom Airzone, OpenWeatherMap, and Konnected metric collectors. · `modules/airzone-exporter/main.go`
- [Gotify API client](https://github.com/daniel-w-innes/nixos/blob/master/modules/konnected-exporter.nix): Go integration · Checked-in client used by the Konnected exporter. · `modules/konnected-exporter.nix`

### Secrets & automation

- [Secret declarations](https://github.com/daniel-w-innes/nixos/blob/master/secrets/secrets.nix): Secret manifest · Maps encrypted credentials to consuming modules. · `secrets/secrets.nix`
- [Encrypted age secrets](https://github.com/daniel-w-innes/nixos/blob/master/secrets/traefik-env.age): age files · Service credentials, API keys, network and exporter tokens. · `secrets/traefik-env.age`
- [Forgejo CI workflows](https://github.com/daniel-w-innes/nixos/blob/master/.forgejo/workflows/test.yml): CI automation · Repository test and update automation. · `.forgejo/workflows/test.yml`
- [Pinned dependencies](https://github.com/daniel-w-innes/nixos/blob/master/flake.lock): Flake lockfile · `flake.lock`

## Connections

- Flake entry point → Host configurations: evaluates
- Flake entry point → Pinned dependencies: pins inputs
- Host configurations → Generic role profiles: imports profiles
- Host configurations → Server service set: enables server roles
- Host configurations → Home profiles: composes users
- Host configurations → Secret declarations: consumes secrets
- Generic role profiles → Server service set: includes server policy
- Server service set → Application services: aggregates
- Server service set → Traefik ingress: configures ingress
- Traefik ingress → Dynamic routes: loads routes
- Dynamic routes → Backend targets: routes to
- Backend targets → Application services: backend services
- Home profiles → Wayland profiles: selects sessions
- Wayland profiles → Compositor config assets: uses runtime configs
- Host configurations → Prometheus enablement: enables monitoring
- Prometheus enablement → Exporter modules: scrapes exporters
- Exporter modules → Go exporter programs: packages
- Go exporter programs → Gotify API client: Konnected integration
- Secret declarations → Encrypted age secrets: declares
- Encrypted age secrets → Application services: credentials
- Encrypted age secrets → Exporter modules: tokens
- Forgejo CI workflows → Flake entry point: tests and updates