Reading paths

This page provides curated reading paths through the documentation organized by goal. Each path sequences documents to build understanding progressively, ensuring prerequisites appear before advanced material. Use these paths when you want a structured approach rather than browsing individual pages.

To use this page effectively, first identify your goal from the path names below. The path overview diagram shows how paths relate, so you can see if foundational paths should be completed first. Then follow the numbered document list in order, skipping items you already understand.

Path overview

The 15 reading paths are organized into five groups: Foundations (Bootstrap, Module System), Understanding (Architecture, AMDiRE, Decisions), Operations (Host Onboarding, User Setup, Secrets, Packages, Fleet, Troubleshooting), Platform deployment (Cloud/NixOS, Darwin), and Support (Contributing, Reference). Two entry points lead to distinct tracks: Bootstrap for operational tasks, Module System for conceptual understanding. These tracks converge at Fleet coordination and Architecture respectively, then branch to deployment targets and deeper topics.

Path 1: First-time bootstrap

For users setting up their first machine with this infrastructure. This path takes you from initial installation through understanding the repository structure and common operations.

1. Getting started - Bootstrap nix and tools
2. Bootstrap to Activation - Understand the full bootstrap process
3. Repository Structure - Familiarize with layout
4. Architecture Overview - High-level understanding
5. Justfile Recipes - Common operations reference

Path 2: Module system foundations

For users wanting to understand the algebraic and category-theoretic foundations enabling Nix configuration composition. This path covers how the module system enables declarative composition through fixpoint computation and deferred evaluation.

Prerequisites

Skip this section if you are already comfortable writing basic Nix modules with mkOption, mkEnableOption, and the { config, lib, ... }: pattern.

1. External: nix.dev module system tutorial - Basic module writing with mkOption, mkEnableOption, and the { config, lib, ... }: pattern
2. Glossary - Terminology orientation (especially: module system, deferredModule, evalModules, fixpoint entries)

Core path

3. Module System Primitives - deferredModule, evalModules, fixpoint computation
4. Flake-parts and the Module System - How flake-parts wraps evalModules
5. Deferred Module Composition - Aspect-based organization pattern
6. ADR-0018: Deferred module composition architecture - Decision rationale
7. Domain Model - Nix ecosystem conceptual model

Path 3: Architecture understanding

For users wanting to comprehend the full system design across all four architectural layers. This path builds from overview to detailed specification, covering each layer in sequence.

1. Architecture Overview - Four-layer architecture summary
2. Module System Primitives - Layer 0 foundations
3. Flake-parts and the Module System - Layer 1 framework
4. Deferred Module Composition - Layer 2 organization
5. Clan Integration - Layer 3 multi-machine coordination
6. Architecture specification - Full AMDiRE system specification
7. ADRs index - Browse all architectural decisions

Path 4: Host onboarding

For users adding new Darwin or NixOS machines to the fleet. This path covers the procedural steps and conceptual understanding needed for machine registration.

1. Host Onboarding - Step-by-step procedure (Darwin vs NixOS sections)
2. Secrets Setup - Required for host secrets
3. System-User Integration - Admin vs standalone user patterns
4. Clan Integration - Machine registry and deployment
5. Deployment Requirements - Platform-specific deployment details

Path 5: User environment setup

For users setting up home-manager configurations for their user accounts. This path explains both the operational steps and the conceptual model for user-level configuration.

1. Home-Manager Onboarding - User environment setup
2. System-User Integration - Admin-integrated vs standalone users
3. Deferred Module Composition - Understanding home module organization
4. Secrets Management - User-level secrets

Path 6: Secrets management

For users working with encrypted secrets and credentials. This path covers both operational procedures and the architectural decisions behind the secrets system.

1. Secrets Management - Operational guide
2. Secrets Setup - Foundational understanding
3. Clan Integration - Secrets architecture section
4. ADR-0011: SOPS secrets management - Original sops-nix decision
5. ADR-0019: Clan-core orchestration - Clan vars migration context

Path 7: Package management and stability

For users handling nixpkgs breakage and custom packages. This path explains the overlay system and multi-channel architecture that enables stable package fallbacks.

1. Handling Broken Packages - Stable fallback procedures
2. Adding Custom Packages - pkgs-by-name pattern
3. Architecture Overview - Multi-channel overlay section
4. ADR-0017: Deferred module composition overlay patterns - Current overlay architecture

Path 8: Multi-machine fleet coordination

For users managing deployments across multiple hosts. This path covers the clan-based coordination system and its integration with the deferred module composition architecture.

1. Clan Integration - Core coordination concepts
2. Architecture Overview - Fleet overview and integration points
3. ADR-0019: Clan-core orchestration - Orchestration decision
4. ADR-0020: Deferred module composition + Clan integration - Pattern integration
5. Usage Model - UC-004: Coordinated service deployment
6. Functional Hierarchy - MC-* multi-host coordination functions

Path 9: Cloud infrastructure provisioning

For users deploying NixOS to cloud providers such as Hetzner or GCP. This path covers the terranix-based infrastructure provisioning and its integration with clan.

1. NixOS Deployment - Cloud deployment tutorial
2. ADR-0021: Terranix infrastructure provisioning - IaC decision
3. Clan Integration - Terranix + Clan integration
4. Usage Model - UC-001: Bootstrap new host
5. Deployment Requirements - DR-002: NixOS deployment

Path 10: Darwin (macOS) deployment

For macOS-specific configuration and deployment. This path covers the complete Darwin workflow from initial setup through platform-specific considerations.

1. Darwin Deployment - Complete darwin workflow
2. Host Onboarding - Darwin section
3. Architecture Overview - Platform support table
4. Deployment Requirements - DR-001: Darwin deployment
5. System Constraints - SC-004: Platform-specific constraints

Path 11: Contributor and developer

For contributors to this infrastructure codebase. This path covers contribution guidelines, testing practices, and CI/CD architecture.

1. Contributing Index - Guidelines overview
2. Commit Conventions - Commit format
3. Testing - Test framework
4. CI/CD Setup - Pipeline details
5. CI Philosophy - CI design principles
6. ADR-0012: GitHub Actions pipeline - CI architecture decision
7. ADR-0016: Per-job content-addressed caching - Cache strategy

Path 12: AMDiRE development methodology

For users wanting to understand the requirements engineering approach used in this project. This path follows the AMDiRE layer structure from context through requirements to architecture.

1. Development Index - AMDiRE overview
2. Context Index - Problem domain documentation
   • Project Scope
   • Stakeholders
   • Goals and Objectives
   • Constraints and Rules
   • Domain Model
   • Glossary
3. Requirements Index - Black-box specification
   • System Vision
   • Usage Model
   • Functional Hierarchy
   • Quality Requirements
4. Architecture Index - Solution space
5. Traceability Index - Requirements tracing

Path 13: Decision archaeology

For users wanting to understand why specific technical decisions were made. This path provides both chronological access and thematic clusters of related decisions.

1. ADRs Index - All decisions chronologically
2. Thematic ADR clusters:
   • Nix fleet: ADR-0017 to ADR-0018 to ADR-0019 to ADR-0020 to ADR-0021
   • CI/CD evolution: ADR-0012 to ADR-0015 to ADR-0016
   • Overlay patterns: ADR-0003 to ADR-0017
   • Monorepo structure: ADR-0004 to ADR-0005 to ADR-0006 to ADR-0007 to ADR-0008
3. Goals and Objectives - What decisions serve
4. Quality Requirements - Quality drivers

Path 14: Quick reference lookup

For users needing immediate command or configuration reference. This path collects the reference materials for quick access during daily operations.

1. Justfile Recipes - Task runner commands
2. Flake Apps - Nix activation commands
3. CI Jobs - CI job reference and local equivalents
4. Repository Structure - Directory layout
5. Glossary - Terminology definitions

Path 15: Troubleshooting and operations

For users debugging issues or performing maintenance. This path collects troubleshooting resources and operational documentation.

1. Troubleshooting CI Cache - CI cache issues
2. Handling Broken Packages - Package breakage resolution
3. CI Jobs - Job reference with troubleshooting
4. Test Harness - Testing infrastructure
5. System Constraints - Known limitations