---
name: bos55-nix-architecture
description: Implementation patterns for NixOS configurations, networking, and service modules.
globs: [".nix", "hosts/**/", "modules//*", "secrets//*"]
---

# NixOS Architecture Skill

When generating or modifying NixOS configuration files for the Bos55 project, strictly adhere to the following architectural patterns:

## 1. Minimal Hardcoding & Dynamic Discovery

- **Local IP Ownership**: Define IPv4/IPv6 addresses **only** within their respective host configuration files (e.g., `hosts/<HostName>/default.nix`). Do not use global IP mapping modules.
- **Inter-Host Discovery**: Resolve a host's IP or port by evaluating its configuration at build time. Never hardcode another host's IP.
  **Pattern Example**:
  ```
  let
    bcConfig = inputs.self.nixosConfigurations.BinaryCache.config;
    bcIp = (pkgs.lib.head bcConfig.networking.interfaces.ens18.ipv4.addresses).address;
  in "http://${bcIp}:8080"
  ```
- **Unified Variables**: Use local variables (e.g., `let dbName = "attic"; in ...`) for shared values between host services and containers to ensure consistency.

## 2. Modular Service Encapsulation

- **Self-Contained Modules**: Service modules (`modules/services/<service>/default.nix`) must manage their own configurations. Prefer `lib.mkOption` over hardcoded strings for domains, ports, and credentials.
- **Firewall Responsibility**: Open ports (e.g., TCP 8080, SSH 22) directly within the service module based on its own options. Do not open service ports manually in host files.
- **Remote Builders**: Define `nix.settings.trusted-users`, `builder` user, and SSH rules directly within the service module if it supports remote building (e.g., Attic).

## 3. Networking & Connectivity

- **Container-to-Host**: Host services must connect to companion containers using the container name, not the bridge IP or `localhost`.
- **Host Resolution**: Map the container name to `127.0.0.1` using `networking.extraHosts` in the host service module to route traffic seamlessly.
- **Domain Deferral**: Client modules must defer their default domain settings to the server module's defined domain option.

## 4. Secrets Management

- **Sops-Nix Exclusivity**: Manage all secrets via `sops-nix`.
- **Centralized Config**: Rely on `modules/common/default.nix` for fleet-wide settings like `defaultSopsFile` and `age.keyFile`.
- **References**: Always reference credentials dynamically using `config.sops.secrets."path/to/secret".path`.

## 5. Security & Documentation

- **Supply Chain Protection**: Always verify and lock Nix flake inputs. Use fixed-output derivations for external resource downloads.
- **Assumptions Documentation**: Clearly document environment assumptions (e.g., Proxmox virtualization, Tailscale networking, and specific IP ranges) in host or service READMEs.
- **Project Structure**: Maintain the strict separation of `hosts/`, `modules/`, `users/`, and `secrets/` to ensure clear ownership and security boundaries.