misterkartoffel/nix-config

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.