# misterkartoffel/nix-config architecture

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

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

## Overview

1. **Repository shape**
   This is a single Nix Flake–based configuration repo that drives both the **NixOS host** and the **Home Manager user environment**. The top-level split is:
   - `hosts/` for machine-specific system config
   - `home/` for user-specific config
   - `modules/` for reusable system and user modules
   - `lib/` for shared helper functions

2. **Entry point and pinning**
   `flake.nix` is the orchestration layer: it pulls together host, user, and shared modules into concrete system/user builds. Dependency pinning is handled via `.tack/` (tack-based input pinning), so the repo is meant to be reproducible rather than ad hoc.

3. **Host boundary: `hosts/ghost`**
   The only host in the tree is `ghost`, with:
   - `default.nix` as the host entry
   - `facter.json` for generated hardware facts
   - `disko.nix` for declarative disk layout and formatting  
   This means machine bring-up is modeled as: hardware facts + disk layout + host options, all composed into a NixOS system.

4. **System layer: `modules/nixos`**
   The NixOS layer is decomposed into small concerns:
   - boot, locale, networking, users, sudo, swap
   - nix and system management
   - ssh and rtkit
   - backups, qbittorrent, nh
   - niri integration
   - `sops.nix` for secrets
   - `impermanence.nix` for persistent state  
   This is the “machine policy” boundary: services, machine identity, storage, and OS-level defaults live here.

5. **User boundary: `home/mimikyu.nix` and `modules/home`**
   User config is separated from system config. `home/mimikyu.nix` is the home entrypoint, and `modules/home` contains all Home Manager modules. This lets the repo define a user session independently of the host, while still being assembled by the same flake.

6. **Desktop/session stack**
   The user session is centered around a Wayland desktop stack:
   - `niri` as the compositor/session manager
   - `swaybg`, `dunst`, `tofi`
   - `ghostty`, `vesktop`, `zen-browser`, `zathura`
   - `stylix` for consistent theming  
   These modules define the visible desktop environment and its supporting utilities.

7. **Shell, terminal, and developer workflow**
   The repo also encodes the day-to-day CLI environment:
   - `zsh`, `direnv`, `nix`, `eza`, `git`
   - `ssh` for access/auth
   - `nix` and `nh` for Nix workflow tooling  
   This is a distinct “operator workflow” layer, separate from GUI apps and from system services.

8. **Editor subsystem: Neovim as a modular stack**
   Neovim is treated as its own subsystem under `modules/home/neovim/`:
   - `nvf.nix` appears to wire in the Neovim framework
   - separate files for `options`, `keymaps`, `languages`
   - Lua support under `lua/`
   - plugin-specific modules under `plugins/`  
   This structure indicates the editor is built as a layered composition: core editor settings, language support, custom Lua functions, and individual plugins.

9. **Mail and calendar pipeline**
   `modules/home/mail/` and `_calendar/` define a fairly complete local mail/calendar workflow:
   - account defaults and account config
   - `offlineimap` and/or `imapnotify` for mailbox sync
   - `msmtp` for sending mail
   - `neomutt` as the mail client
   - `oama` for auth/token handling
   - `vdirsyncer` for calendar/contact sync  
   The data flow here is external providers → sync tools → local mail/calendar state → mail client.

10. **State persistence vs. impermanence**
   Both `modules/nixos/impermanence.nix` and `modules/home/impermanence.nix` indicate that persistence is intentional and selective. That suggests a mostly declarative, possibly ephemeral base system with explicit persisted paths for user and system state. This is an important architectural boundary because it separates “rebuildable config” from “must survive reboot” data.

11. **Secrets management**
   `modules/nixos/sops.nix` and `modules/home/sops.nix` show that secrets are handled declaratively with sops-nix. The secret boundary is therefore not embedded in plain config; instead, modules consume decrypted secrets at evaluation/deploy time as needed.

12. **Shared helpers**
   `lib/attrsets.nix` and `lib/paths.nix` are custom support code exported as `lib.custom`. These are likely used to keep module code DRY and centralize common transformations/path logic across host and home configs.

13. **Operational picture**
   The repo is designed so that a host build pulls in:
   - host-specific hardware/disk details
   - reusable NixOS modules
   - user-session modules via Home Manager
   - secrets and persistence policies  
   The result is a layered configuration model where the flake is the coordinator, `hosts/` defines machine identity, and `home/` defines the user experience.

14. **What to draw in an architecture diagram**
   The main diagram should show three concentric or side-by-side domains:
   - **Flake orchestration**
   - **NixOS system layer** for `ghost`
   - **Home Manager user layer** for `mimikyu`  
   Then annotate cross-cutting dependencies: `sops-nix`, `impermanence`, `stylix`, and `lib.custom`. The important external inputs are hardware facts (`facter.json`), disk layout (`disko.nix`), and pinned dependencies via tack.

Main entry points: [`modules/home/xdg.nix`](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/xdg.nix) (home modules), [`flake.nix`](https://github.com/misterkartoffel/nix-config/blob/main/flake.nix) (flake.nix), [`modules/nixos/modules.nix`](https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/modules.nix) (system modules), [`hosts/ghost/default.nix`](https://github.com/misterkartoffel/nix-config/blob/main/hosts/ghost/default.nix) (ghost host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_flake["Flake orchestration"]
  node_flake["flake.nix<br/>orchestrator<br/>[flake.nix]"]
  node_tack[".tack pins<br/>pinning<br/>[pins.lock.json]"]
end

subgraph group_g_host["Host config"]
  node_ghost_host["ghost host<br/>nixos-host<br/>[default.nix]"]
  node_ghost_facter["hardware facts<br/>[facter.json]"]
  node_ghost_disko["disk layout<br/>storage-plan<br/>[disko.nix]"]
end

subgraph group_g_system["NixOS modules"]
  node_nixos_modules["system modules<br/>nixos-layer<br/>[modules.nix]"]
  node_system_core["core policy<br/>nixos-core<br/>[system.nix]"]
  node_system_services["services<br/>[ssh.nix]"]
  node_system_state["state layers<br/>nixos-state<br/>[impermanence.nix]"]
end

subgraph group_g_home["Home Manager"]
  node_home_entry["mimikyu home<br/>home-entry<br/>[mimikyu.nix]"]
  node_home_modules["home modules<br/>home-layer<br/>[xdg.nix]"]
  node_desktop["desktop stack<br/>wayland-session<br/>[niri.nix]"]
  node_workflow["shell workflow<br/>cli-workflow<br/>[zsh.nix]"]
  node_stylix(("Stylix<br/>theming<br/>[stylix.nix]"))
  node_sops_home(("home secrets<br/>[sops.nix]"))
  node_impermanence_home(("home persistence<br/>[impermanence.nix]"))
end

subgraph group_g_editor["Neovim stack"]
  node_neovim["Neovim<br/>editor-stack<br/>[nvf.nix]"]
end

subgraph group_g_mail["Mail stack"]
  node_mail["mail/calendar<br/>messaging-pipeline<br/>[_defaults.nix]"]
end

subgraph group_g_lib["Shared lib"]
  node_custom_lib["custom lib<br/>helpers<br/>[default.nix]"]
end

node_flake -->|"pins inputs"| node_tack
node_flake -->|"builds host"| node_ghost_host
node_flake -->|"builds user"| node_home_entry
node_flake -->|"includes"| node_nixos_modules
node_flake -->|"includes"| node_home_modules
node_flake -->|"exports"| node_custom_lib
node_ghost_host -->|"uses facts"| node_ghost_facter
node_ghost_host -->|"uses disk plan"| node_ghost_disko
node_ghost_host -->|"imports"| node_nixos_modules
node_nixos_modules -->|"base policy"| node_system_core
node_nixos_modules -->|"service layer"| node_system_services
node_nixos_modules -->|"state layer"| node_system_state
node_system_state -.->|"uses helpers"| node_custom_lib
node_home_entry -->|"imports"| node_home_modules
node_home_modules -->|"session"| node_desktop
node_home_modules -->|"workflow"| node_workflow
node_home_modules -->|"editor"| node_neovim
node_home_modules -->|"mail flow"| node_mail
node_home_modules -->|"themes"| node_stylix
node_home_modules -->|"secrets"| node_sops_home
node_home_modules -->|"persistence"| node_impermanence_home
node_neovim -.->|"uses helpers"| node_custom_lib
node_mail -.->|"uses helpers"| node_custom_lib

click node_flake "https://github.com/misterkartoffel/nix-config/blob/main/flake.nix"
click node_tack "https://github.com/misterkartoffel/nix-config/blob/main/.tack/pins.lock.json"
click node_ghost_host "https://github.com/misterkartoffel/nix-config/blob/main/hosts/ghost/default.nix"
click node_ghost_facter "https://github.com/misterkartoffel/nix-config/blob/main/hosts/ghost/facter.json"
click node_ghost_disko "https://github.com/misterkartoffel/nix-config/blob/main/hosts/ghost/disko.nix"
click node_nixos_modules "https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/modules.nix"
click node_system_core "https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/system.nix"
click node_system_services "https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/ssh.nix"
click node_system_state "https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/impermanence.nix"
click node_home_entry "https://github.com/misterkartoffel/nix-config/blob/main/home/mimikyu.nix"
click node_home_modules "https://github.com/misterkartoffel/nix-config/blob/main/modules/home/xdg.nix"
click node_desktop "https://github.com/misterkartoffel/nix-config/blob/main/modules/home/niri.nix"
click node_workflow "https://github.com/misterkartoffel/nix-config/blob/main/modules/home/zsh.nix"
click node_neovim "https://github.com/misterkartoffel/nix-config/blob/main/modules/home/neovim/nvf.nix"
click node_mail "https://github.com/misterkartoffel/nix-config/blob/main/modules/home/mail/_defaults.nix"
click node_stylix "https://github.com/misterkartoffel/nix-config/blob/main/modules/home/stylix.nix"
click node_sops_home "https://github.com/misterkartoffel/nix-config/blob/main/modules/home/sops.nix"
click node_impermanence_home "https://github.com/misterkartoffel/nix-config/blob/main/modules/home/impermanence.nix"
click node_custom_lib "https://github.com/misterkartoffel/nix-config/blob/main/lib/default.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_tack,node_custom_lib toneBlue
class node_ghost_host,node_ghost_facter,node_ghost_disko toneAmber
class node_nixos_modules,node_system_core,node_system_services,node_system_state toneMint
class node_home_entry,node_home_modules,node_desktop,node_workflow,node_stylix,node_sops_home,node_impermanence_home toneRose
class node_neovim toneIndigo
class node_mail toneTeal
```

## Components

### Flake orchestration

Top-level composition and dependency pinning.

- [flake.nix](https://github.com/misterkartoffel/nix-config/blob/main/flake.nix): orchestrator · Assembles host, home, shared modules, and outputs. · `flake.nix`
- [.tack pins](https://github.com/misterkartoffel/nix-config/blob/main/.tack/pins.lock.json): pinning · Locked dependency inputs for reproducible builds. · `.tack/pins.lock.json`

### Host config

Machine-specific NixOS bring-up for ghost.

- [ghost host](https://github.com/misterkartoffel/nix-config/blob/main/hosts/ghost/default.nix): nixos-host · Machine entrypoint for the only defined host. · `hosts/ghost/default.nix`
- [hardware facts](https://github.com/misterkartoffel/nix-config/blob/main/hosts/ghost/facter.json): facts · Generated host facts consumed during system bring-up. · `hosts/ghost/facter.json`
- [disk layout](https://github.com/misterkartoffel/nix-config/blob/main/hosts/ghost/disko.nix): storage-plan · Declarative partitioning and filesystem layout. · `hosts/ghost/disko.nix`

### NixOS modules

Reusable machine policy and services.

- [system modules](https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/modules.nix): nixos-layer · Composed NixOS policy, services, and defaults. · `modules/nixos/modules.nix`
- [core policy](https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/system.nix): nixos-core · Boot, locale, networking, users, sudo, swap, and base system settings. · `modules/nixos/system.nix`
- [services](https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/ssh.nix): nixos-services · SSH, rtkit, backups, qbittorrent, nh, and related services. · `modules/nixos/ssh.nix`
- [state layers](https://github.com/misterkartoffel/nix-config/blob/main/modules/nixos/impermanence.nix): nixos-state · Impermanence and secrets handling for the machine layer. · `modules/nixos/impermanence.nix`

### Home Manager

User session and workstation modules.

- [mimikyu home](https://github.com/misterkartoffel/nix-config/blob/main/home/mimikyu.nix): home-entry · Home Manager entrypoint for the user environment. · `home/mimikyu.nix`
- [home modules](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/xdg.nix): home-layer · Reusable user-session modules and workstation defaults. · `modules/home/xdg.nix`
- [desktop stack](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/niri.nix): wayland-session · Niri-centered Wayland desktop and companion apps. · `modules/home/niri.nix`
- [shell workflow](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/zsh.nix): cli-workflow · Shell, editor access, Nix tooling, and daily operator utilities. · `modules/home/zsh.nix`
- [Stylix](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/stylix.nix): theming · Shared visual theming across desktop and applications. · `modules/home/stylix.nix`
- [home secrets](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/sops.nix): secrets · Home-level secret consumption via sops-nix. · `modules/home/sops.nix`
- [home persistence](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/impermanence.nix): persistence · Selective persistence for user state in an impermanent base. · `modules/home/impermanence.nix`

### Neovim stack

Layered editor subsystem inside Home Manager.

- [Neovim](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/neovim/nvf.nix): editor-stack · Modular editor subsystem with options, languages, Lua, and plugins. · `modules/home/neovim/nvf.nix`

### Mail stack

Mail and calendar workflow.

- [mail/calendar](https://github.com/misterkartoffel/nix-config/blob/main/modules/home/mail/_defaults.nix): messaging-pipeline · Local mail and calendar sync, transport, and client setup. · `modules/home/mail/_defaults.nix`

### Shared lib

Common helpers reused across modules.

- [custom lib](https://github.com/misterkartoffel/nix-config/blob/main/lib/default.nix): helpers · Shared attrset and path helpers exported as lib.custom. · `lib/default.nix`

## Connections

- flake.nix → .tack pins: pins inputs · Uses tack-managed dependency locks for reproducibility.
- flake.nix → ghost host: builds host · Composes the machine configuration for ghost.
- flake.nix → mimikyu home: builds user · Assembles the Home Manager profile for mimikyu.
- flake.nix → system modules: includes · Pulls in reusable system modules.
- flake.nix → home modules: includes · Pulls in reusable home modules.
- flake.nix → custom lib: exports · Makes shared helper functions available to modules.
- ghost host → hardware facts: uses facts · Consumes generated hardware facts for host bring-up.
- ghost host → disk layout: uses disk plan · Applies declarative storage layout for the machine.
- ghost host → system modules: imports · Composes the host from reusable NixOS policy modules.
- system modules → core policy: base policy · Defines the core OS configuration.
- system modules → services: service layer · Adds services and operational tools.
- system modules → state layers: state layer · Handles persistence and secrets for the system.
- state layers → custom lib: uses helpers · Relies on shared helper functions where needed.
- mimikyu home → home modules: imports · Builds the user profile from modular home config.
- home modules → desktop stack: session · Defines the visible desktop and app stack.
- home modules → shell workflow: workflow · Defines shell, Nix, and daily CLI tooling.
- home modules → Neovim: editor · Includes the modular Neovim configuration.
- home modules → mail/calendar: mail flow · Includes mail and calendar modules.
- home modules → Stylix: themes · Applies consistent theming to user-facing components.
- home modules → home secrets: secrets · Consumes decrypted secrets at the home layer.
- home modules → home persistence: persistence · Defines persisted user state paths.
- Neovim → custom lib: uses helpers · Shares helper logic and path/attrset utilities.
- mail/calendar → custom lib: uses helpers · May reuse shared utility functions for account and path composition.