# minegameytb/nixos-configuration architecture

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

- Interactive diagram: https://gitdiagram.com/minegameytb/nixos-configuration
- Repository: https://github.com/minegameytb/nixos-configuration

## Overview

1. This is a Nix flake–based NixOS configuration repository. The top-level `flake.nix` and `flake.lock` define the pinned package set and are the central composition point for all system, user, and package outputs.

2. The repo is split by responsibility, not by application: `configurations/` holds NixOS system configuration, `home-manager/` holds user-session configuration, `pkgs/` contains local package definitions, and `profiles/` contains host-specific bundles that combine the right pieces for a given machine.

3. The NixOS layer is organized as a hierarchy of modules. `configurations/configuration.nix` appears to be the root system entry, with reusable “common” modules under `configurations/configs/common`, role-specific modules under `configurations/configs/specific`, and cross-cutting services under `configurations/configs/system`.

4. Hardware and disk layout are intentionally separated from the main system policy. `configurations/hardware-configuration/` contains per-machine hardware files, while `configurations/disko-configuration/` contains declarative disk layouts for installation and formatting. This means machine provisioning is a first-class part of the architecture, not an afterthought.

5. Boot and storage are modularized around multiple platform paths. Under `configurations/configs/bootloader/` there are distinct branches for GRUB2, systemd-boot, EFI mountpoint handling, and BIOS/EFI variants, which suggests the final host profile chooses one boot path depending on firmware and disk format.

6. The repo distinguishes “base system policy” from “feature bundles.” Common system settings include users, timezone, security, shell, fonts, Nix settings, and system apps. Specific bundles then add desktop, laptop, container, or VM behavior without duplicating the base layer.

7. Desktop configuration is its own subsystem. `configurations/configs/specific/desktop/` covers GNOME, X11, sound, printer support, Plymouth, autologin, and browser choices. It also includes a large games subtree for Steam, Lutris, Heroic, PrismLauncher, emulators, Waydroid, and Flatpak-based game installs.

8. Virtualization is modeled symmetrically on both sides: `configurations/configs/specific/vm/host` configures host-side hypervisor features such as QEMU/KVM and VMware Workstation, while `configurations/configs/specific/vm/guest` configures guest integration such as SSH, Tailscale, Nextcloud, and QEMU guest support.

9. `home-manager/` is the user-space counterpart to the NixOS modules. It has common CLI/editor settings, customization modules for apps and themes, desktop GUI package sets, and separate “standalone” versus “NixOS-integrated” paths. This indicates user environment configuration is reusable both inside and outside the NixOS system build.

10. The repo uses custom module extensions and overlays to bend upstream packages to its needs. `configurations/modules/` and `home-manager/config-modules/` add feature modules such as declarative Flatpak, nix-index-db, lazyvim, and browser hardening; `configurations/configs/overlays/` and top-level `overlay.nix` adjust upstream packages like coreutils, GNOME components, AppImage support, and browser-related packages.

11. Local package development lives under `pkgs/`, with explicit derivations such as `sshrm`, `rm-only`, and an FHS development environment. This is a separate boundary from system configuration: these packages can be injected into NixOS or Home Manager without changing the system module structure.

12. Host selection is captured in `profiles/` and `hm-profiles/`. These files likely assemble a complete machine identity by combining a hardware target, a boot mode, a GUI/no-GUI choice, and a user profile. The README’s examples for `hp-probook`, `hp-240`, and VM profiles confirm that profile composition is the main way to produce concrete hosts.

13. There are some repo-specific operational helpers. `script/update-flake` automates lockfile updates and commits, `script/mksymlink` creates symlinks into a home directory, and `build.sh`/`Makefile` likely wrap common Nix commands for development and deployment. These scripts support repo maintenance rather than being part of the runtime system.

14. Installation and provisioning flow through Disko and NixOS install. The README shows disk creation/mounting via `disko`, then host build installation via `nixos-install --flake`. So the architecture includes both declarative OS composition and declarative disk provisioning as separate but coordinated stages.

Main entry points: [`configurations/configuration.nix`](https://github.com/minegameytb/nixos-configuration/blob/flake/configurations/configuration.nix) (System root), [`flake.nix`](https://github.com/minegameytb/nixos-configuration/blob/flake/flake.nix) (Flake), [`home-manager/home.nix`](https://github.com/minegameytb/nixos-configuration/blob/flake/home-manager/home.nix) (Home root), [`profiles`](https://github.com/minegameytb/nixos-configuration/tree/flake/profiles) (Profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_flake["Flake & entrypoints"]
  node_flake["Flake<br/>composition root<br/>[flake.nix]"]
  node_lock["Lockfile<br/>pinned inputs<br/>[flake.lock]"]
end

subgraph group_group_nixos["NixOS system"]
  node_root_system["System root<br/>nixos entry<br/>[configuration.nix]"]
  node_common_opts["Common opts<br/>system baseline"]
  node_security["Security<br/>system policy<br/>[security.nix]"]
  node_networking["Networking<br/>system policy<br/>[default.nix]"]
  node_system_services["System services<br/>service layer"]
  node_bootloader["Bootloader<br/>boot stack"]
  node_hardware["Hardware<br/>machine facts"]
  node_disko["Disk layout<br/>provisioning"]
  node_overlays["Overlays<br/>package overrides"]
  node_modules["Modules"]
  node_system_specific["Specific bundles<br/>feature bundles"]
  node_desktop["Desktop<br/>gui bundle"]
  node_vm_host["VM host<br/>host bundle"]
  node_vm_guest["VM guest<br/>guest bundle"]
end

subgraph group_group_home["Home Manager"]
  node_home_root["Home root<br/>home entry<br/>[home.nix]"]
  node_hm_common["Home common<br/>user baseline"]
  node_hm_custom["Customization<br/>user theming"]
  node_hm_desktop["Desktop apps<br/>gui packages<br/>[gui-packages.nix]"]
  node_hm_standalone["Standalone HM<br/>standalone mode"]
  node_hm_nixos["NixOS HM<br/>integrated mode"]
end

subgraph group_group_profiles["Profiles"]
  node_profiles["Profiles<br/>host assembly"]
  node_hm_profiles["HM profiles<br/>user assembly"]
end

subgraph group_group_pkgs["Local packages"]
  node_local_pkgs["Local pkgs<br/>package set"]
end

subgraph group_group_ops["Ops & scripts"]
  node_scripts["Scripts<br/>maintenance tools"]
end

node_flake -->|"pins"| node_lock
node_flake -->|"exports"| node_root_system
node_flake -->|"exports"| node_home_root
node_flake -->|"assembles"| node_profiles
node_flake -->|"assembles"| node_hm_profiles
node_flake -->|"packages"| node_local_pkgs
node_flake -->|"applies"| node_overlays
node_profiles -->|"selects"| node_hardware
node_profiles -->|"selects"| node_disko
node_profiles -->|"selects"| node_bootloader
node_profiles -->|"combines"| node_system_specific
node_system_specific -->|"includes"| node_desktop
node_system_specific -->|"includes"| node_vm_host
node_system_specific -->|"includes"| node_vm_guest
node_root_system -->|"imports"| node_common_opts
node_root_system -->|"imports"| node_security
node_root_system -->|"imports"| node_networking
node_root_system -->|"imports"| node_system_services
node_root_system -->|"imports"| node_bootloader
node_root_system -->|"imports"| node_hardware
node_root_system -->|"imports"| node_disko
node_root_system -->|"extends"| node_modules
node_root_system -->|"uses"| node_overlays
node_root_system -->|"uses"| node_local_pkgs
node_desktop -->|"uses"| node_modules
node_desktop -->|"uses"| node_overlays
node_vm_host -->|"uses"| node_modules
node_vm_guest -->|"uses"| node_modules
node_home_root -->|"imports"| node_hm_common
node_home_root -->|"imports"| node_hm_custom
node_home_root -->|"imports"| node_hm_desktop
node_home_root -->|"selects"| node_hm_standalone
node_home_root -->|"selects"| node_hm_nixos
node_hm_standalone -.->|"matches"| node_hm_profiles
node_hm_nixos -.->|"matches"| node_profiles
node_hm_custom -->|"extends"| node_modules
node_home_root -->|"uses"| node_local_pkgs
node_scripts -->|"maintains"| node_flake

click node_flake "https://github.com/minegameytb/nixos-configuration/blob/flake/flake.nix"
click node_lock "https://github.com/minegameytb/nixos-configuration/blob/flake/flake.lock"
click node_root_system "https://github.com/minegameytb/nixos-configuration/blob/flake/configurations/configuration.nix"
click node_common_opts "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/common/system-opts"
click node_security "https://github.com/minegameytb/nixos-configuration/blob/flake/configurations/configs/common/security.nix"
click node_networking "https://github.com/minegameytb/nixos-configuration/blob/flake/configurations/configs/networking/default.nix"
click node_system_services "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/system/services"
click node_bootloader "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/bootloader"
click node_hardware "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/hardware-configuration"
click node_disko "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/disko-configuration"
click node_overlays "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/overlays"
click node_modules "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/modules"
click node_system_specific "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/specific"
click node_desktop "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/specific/desktop"
click node_vm_host "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/specific/vm/host"
click node_vm_guest "https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/specific/vm/guest"
click node_home_root "https://github.com/minegameytb/nixos-configuration/blob/flake/home-manager/home.nix"
click node_hm_common "https://github.com/minegameytb/nixos-configuration/tree/flake/home-manager/configs/common"
click node_hm_custom "https://github.com/minegameytb/nixos-configuration/tree/flake/home-manager/configs/customization"
click node_hm_desktop "https://github.com/minegameytb/nixos-configuration/blob/flake/home-manager/configs/desktop/gui-packages.nix"
click node_hm_standalone "https://github.com/minegameytb/nixos-configuration/tree/flake/home-manager/configs/specific/standalone"
click node_hm_nixos "https://github.com/minegameytb/nixos-configuration/tree/flake/home-manager/configs/specific/nixos"
click node_profiles "https://github.com/minegameytb/nixos-configuration/tree/flake/profiles"
click node_hm_profiles "https://github.com/minegameytb/nixos-configuration/tree/flake/hm-profiles"
click node_local_pkgs "https://github.com/minegameytb/nixos-configuration/tree/flake/pkgs"
click node_scripts "https://github.com/minegameytb/nixos-configuration/tree/flake/script"

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 toneBlue
class node_root_system,node_common_opts,node_security,node_networking,node_system_services,node_bootloader,node_hardware,node_disko,node_overlays,node_modules,node_system_specific,node_desktop,node_vm_host,node_vm_guest toneAmber
class node_home_root,node_hm_common,node_hm_custom,node_hm_desktop,node_hm_standalone,node_hm_nixos toneMint
class node_profiles,node_hm_profiles toneRose
class node_local_pkgs toneIndigo
class node_scripts toneTeal
```

## Components

### Flake & entrypoints

Top-level composition and repo orchestration.

- [Flake](https://github.com/minegameytb/nixos-configuration/blob/flake/flake.nix): composition root · Pinned input set and output composition entrypoint. · `flake.nix`
- [Lockfile](https://github.com/minegameytb/nixos-configuration/blob/flake/flake.lock): pinned inputs · Resolved dependency versions for the flake. · `flake.lock`

### NixOS system

System configuration, hardware, storage, boot, services, and overlays.

- [System root](https://github.com/minegameytb/nixos-configuration/blob/flake/configurations/configuration.nix): nixos entry · Main NixOS configuration entrypoint. · `configurations/configuration.nix`
- [Common opts](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/common/system-opts): system baseline · Shared base policy such as users, time, shell, fonts, Nix, and packages. · `configurations/configs/common/system-opts`
- [Security](https://github.com/minegameytb/nixos-configuration/blob/flake/configurations/configs/common/security.nix): system policy · Common security-related NixOS settings. · `configurations/configs/common/security.nix`
- [Networking](https://github.com/minegameytb/nixos-configuration/blob/flake/configurations/configs/networking/default.nix): system policy · Shared network configuration layer. · `configurations/configs/networking/default.nix`
- [System services](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/system/services): service layer · Cross-cutting services and runtime behavior. · `configurations/configs/system/services`
- [Bootloader](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/bootloader): boot stack · Boot path selection across EFI, BIOS, GRUB, and systemd-boot. · `configurations/configs/bootloader`
- [Hardware](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/hardware-configuration): machine facts · Per-machine hardware definitions and firmware-specific facts. · `configurations/hardware-configuration`
- [Disk layout](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/disko-configuration): provisioning · Declarative disk partitioning and formatting layouts. · `configurations/disko-configuration`
- [Overlays](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/overlays): package overrides · Nixpkgs overlays and package adjustments used by the system. · `configurations/configs/overlays`
- [Modules](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/modules): custom modules · Additional NixOS modules extending upstream behavior. · `configurations/modules`
- [Specific bundles](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/specific): feature bundles · Role-specific additions for desktop, laptop, container, and VM machines. · `configurations/configs/specific`
- [Desktop](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/specific/desktop): gui bundle · GUI-focused configuration including GNOME, X11, sound, printers, and games. · `configurations/configs/specific/desktop`
- [VM host](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/specific/vm/host): host bundle · Host-side virtualization features for QEMU/KVM and VMware. · `configurations/configs/specific/vm/host`
- [VM guest](https://github.com/minegameytb/nixos-configuration/tree/flake/configurations/configs/specific/vm/guest): guest bundle · Guest integration such as SSH, Tailscale, Nextcloud, and QEMU guest support. · `configurations/configs/specific/vm/guest`

### Home Manager

User-session configuration for standalone and NixOS-integrated use.

- [Home root](https://github.com/minegameytb/nixos-configuration/blob/flake/home-manager/home.nix): home entry · Primary Home Manager entrypoint. · `home-manager/home.nix`
- [Home common](https://github.com/minegameytb/nixos-configuration/tree/flake/home-manager/configs/common): user baseline · Shared CLI, editor, and user configuration defaults. · `home-manager/configs/common`
- [Customization](https://github.com/minegameytb/nixos-configuration/tree/flake/home-manager/configs/customization): user theming · App, CLI, and theme customization modules. · `home-manager/configs/customization`
- [Desktop apps](https://github.com/minegameytb/nixos-configuration/blob/flake/home-manager/configs/desktop/gui-packages.nix): gui packages · GUI package sets for desktop user environments. · `home-manager/configs/desktop/gui-packages.nix`
- [Standalone HM](https://github.com/minegameytb/nixos-configuration/tree/flake/home-manager/configs/specific/standalone): standalone mode · Home Manager configuration path usable outside NixOS. · `home-manager/configs/specific/standalone`
- [NixOS HM](https://github.com/minegameytb/nixos-configuration/tree/flake/home-manager/configs/specific/nixos): integrated mode · Home Manager configuration path for NixOS-integrated use. · `home-manager/configs/specific/nixos`

### Profiles

Host and machine composition layers.

- [Profiles](https://github.com/minegameytb/nixos-configuration/tree/flake/profiles): host assembly · Concrete machine profiles combining hardware, boot mode, and feature bundles. · `profiles`
- [HM profiles](https://github.com/minegameytb/nixos-configuration/tree/flake/hm-profiles): user assembly · User-profile assembly for desktop, server, and VM variants. · `hm-profiles`

### Local packages

Repository-local derivations and helper packages.

- [Local pkgs](https://github.com/minegameytb/nixos-configuration/tree/flake/pkgs): package set · Repository-local derivations injected into the system or user environment. · `pkgs`

### Ops & scripts

Maintenance and convenience tooling.

- [Scripts](https://github.com/minegameytb/nixos-configuration/tree/flake/script): maintenance tools · Repository maintenance and convenience scripts. · `script`

## Connections

- Flake → Lockfile: pins · The flake resolves inputs through the lockfile.
- Flake → System root: exports · System outputs are composed from the top-level flake.
- Flake → Home root: exports · Home Manager outputs are composed from the top-level flake.
- Flake → Profiles: assembles · Machine profiles are built as flake outputs.
- Flake → HM profiles: assembles · User profiles are built as flake outputs.
- Flake → Local pkgs: packages · Local package derivations are exposed through the flake.
- Flake → Overlays: applies · Package overrides feed into the flake's package set.
- Profiles → Hardware: selects · Profiles choose the target hardware definition.
- Profiles → Disk layout: selects · Profiles choose a declarative storage layout.
- Profiles → Bootloader: selects · Profiles choose the appropriate boot path.
- Profiles → Specific bundles: combines · Profiles compose feature bundles into a host.
- Specific bundles → Desktop: includes · Desktop hosts get GUI and games features.
- Specific bundles → VM host: includes · Host virtualization bundles are available for VM-capable machines.
- Specific bundles → VM guest: includes · Guest integration bundles are available for guest images.
- System root → Common opts: imports · The system root pulls in the shared baseline modules.
- System root → Security: imports · Security policy is part of the system baseline.
- System root → Networking: imports · Network configuration is part of the system baseline.
- System root → System services: imports · Cross-cutting services are wired into the system root.
- System root → Bootloader: imports · Boot modules are composed into the system root.
- System root → Hardware: imports · Hardware facts are consumed by the system configuration.
- System root → Disk layout: imports · Disk provisioning is paired with the system configuration.
- System root → Modules: extends · Custom NixOS modules extend the system root.
- System root → Overlays: uses · System configuration consumes local package overlays.
- System root → Local pkgs: uses · Local derivations are made available to the system.
- Desktop → Modules: uses · Desktop features rely on custom modules where needed.
- Desktop → Overlays: uses · Desktop-specific package tweaks come from overlays.
- VM host → Modules: uses · Virtualization host features may depend on custom modules.
- VM guest → Modules: uses · Guest integration may depend on custom modules.
- Home root → Home common: imports · The user environment starts from common Home Manager modules.
- Home root → Customization: imports · Custom app and theme modules are included in Home Manager.
- Home root → Desktop apps: imports · Desktop user packages are added when relevant.
- Home root → Standalone HM: selects · Standalone Home Manager is one supported mode.
- Home root → NixOS HM: selects · NixOS-integrated Home Manager is the other supported mode.
- Standalone HM → HM profiles: matches · Standalone Home Manager uses profile-style composition.
- NixOS HM → Profiles: matches · Integrated Home Manager is aligned with host profiles.
- Customization → Modules: extends · User-side custom modules mirror system-side extensions.
- Home root → Local pkgs: uses · User environments can consume repository-local packages.
- Scripts → Flake: maintains · Helper scripts support flake and repository maintenance.
