# Reference Map

## Module Directories
- apps → `modules/apps/` (desktop/workstation apps, auto-imported)
- dev → `modules/dev/` (language toolchains and dev shells, auto-imported)
- scripts → `modules/scripts/` (script units built via `mkscript`, auto-imported)
- servers → `modules/servers/` (reverse-proxied services built via `mkserver`)
- services → `modules/services/` (supporting services like syncthing, wireguard)
- shell → `modules/shell/` (shell customizations and CLI tooling)
- network → `modules/network/` (networking rules, firewall helpers)
- users → `modules/users/` (user-related options)
- nix → `modules/nix/` (Nix configuration and helpers)
- patches → `patches/` (patch artifacts referenced by modules)
- factories → `modules/factories/` (`mkserver.nix`, `mkscript.nix` shared helpers)

## Auto-Import Rules
- Source: `modules/modules.nix` uses `inputs.self.lib.autoImport` to load `.nix` files from module directories.
- Filter: Excludes `librewolf.nix`; all other `.nix` files in target dirs are loaded automatically.
- Implication: Place new modules in the correct category directory with a `.nix` filename; no manual import wiring required unless adding a new factory.

## Hosts and Roles
- Configs: `hosts/<name>/configuration.nix` with toggles in `hosts/<name>/toggles.nix`.
- Active hosts: `workstation`, `server`, `miniserver`, `galaxy`, `emacs`, `vps`.
- Roles:
  - workstation: developer desktop; provides build power for distributed builds.
  - server: primary services host; runs most services and WireGuard targets.
  - miniserver: small-footprint server.
  - galaxy: small server variant using nixpkgs-small.
  - emacs: VM profile, `my.secureHost = false` for secret-free usage.
  - vps: Linode VPS image target, secure host with enrollment-based secrets.
- Network maps: `my.ips` and `my.interfaces` declared in `modules/modules.nix`; host toggles may override.

## Proxy, Firewall, and Networking
- Proxy enablement: `my.enableProxy` toggles Nginx reverse proxy; assertions require at least one `my.servers.*.enableProxy` when enabled.
- Proxy helpers: use `parts/core.nix` helpers (`proxy`, `proxyReverse`, `proxyReverseFix` for header preservation, `proxyReversePrivate` for mutual TLS). `mkserver` supplies `host`, `ip`, `url`, `enableProxy`, and `useDefaultProxy`.
- Default proxying: any server with `enableProxy = true` gets a `proxyReverse` vhost unless `useDefaultProxy = false` or it is listed in `proxyReverseFix` / `proxyReversePrivate`.
- Main server selection: `my.mainServer` chooses where services live by default (default `vps`); `mkserver` sets `isLocal` based on this and picks IPs from `my.ips`.
- Firewall generation: `inputs.self.lib.generateFirewallPorts` combines static ports, additional ports, and service ports from `my.servers` (excluding native firewall services). Use `my.network.firewall` settings and `getServicesWithNativeFirewall` to derive open ports.

## Secrets Map
- Files and purposes:
  - `secrets/certs.yaml` → certificates and TLS material.
  - `secrets/env.yaml` → environment variables for services (e.g., lidarr-mb-gap).
  - `secrets/gallery.yaml` → media/gallery credentials.
  - `secrets/homepage.yaml` → homepage widget secrets.
  - `secrets/keys.yaml` → SSH/private keys and key ownership.
  - `secrets/wireguard.yaml` → WireGuard peers and private keys.
  - `secrets/secrets.yaml` → default SOPS file (general secrets, fallback when unspecified).
  - `secrets/ssh/` → host SSH keys and related artifacts.
- secureHost: Only hosts with `my.secureHost = true` consume SOPS entries and WireGuard interfaces. Keep secret references behind `lib.mkIf config.my.secureHost`; proxy-only services that use private certs must still declare their cert secrets when `enableProxy = true`.

## Stylix and Theming
- Stylix module: `config/stylix.nix` and stylix inputs in `flake.nix` apply theming. Host toggle `my.stylix.enable` controls activation (see host toggles).
- Schemes and assets: Imported via Stylix inputs; wallpapers/fonts sourced from external flakes (`wallpapers`, `fonts`).

## Playbooks and Templates
- Playbook template: `docs/playbooks/template.md`
- Workflows: `docs/playbooks/add-module.md`, `add-server.md`, `add-script.md`, `add-host-toggle.md`, `add-secret.md`
- Constitution link-back: `docs/constitution.md` sections on terminology, proxies, secrets, and maintenance.
- MCP server reference: `docs/reference/mcp-server.md` (tool catalog, `nixos-mcp` wrapper, invocation, sync-docs)

## Quick Audit Checklist
- Module coverage: All categories (apps, dev, scripts, servers, services, shell, network, users, nix, patches) have corresponding entries and auto-import rules.
- Host coverage: Active hosts listed with roles and secureHost status; `mainServer` noted.
- Proxy rules: `enableProxy` usage, proxy helper selection, and `my.ips` mappings documented.
- Secrets map: Every secrets file and secureHost gating captured; new secret types aligned to file purposes.
- Discoverability: Paths reachable within two clicks from `docs/constitution.md`.