# alinkbetweennets/nix architecture

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

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

## Overview

This project is a comprehensive, declarative NixOS infrastructure configuration that uses the Nix/NixOS and Home Manager ecosystems to manage and provision a wide variety of systems—from desktop and gaming setups to servers and even embedded machines. The overall structure is highly modular, with separate directories for machine-specific configurations, reusable modules for common system settings and services, personalized Home Manager configurations, custom package builds, CI workflows, and secrets management.

##### Main Components
a. Machines: The “machines” directory contains configuration files (e.g., configuration.nix, disk-config.nix, hardware-configuration.nix) for various systems (like dn, fn, hn, etc.). Each machine can be treated as a node in the architecture.
b. Modules: Under “modules”, there are multiple reusable NixOS modules (e.g., boot, common, services, hardware, filesystems, container support, etc.). These provide configurable building blocks that abstract common system functionality.
c. Home Manager: The “home-manager” section provides user-specific configurations, including modules that tailor user environments (for tools like neovim, git, shell, etc.) across different profiles.
d. Packages (pkgs): The “pkgs” directory includes custom package definitions and themes. These packages may be employed by both system-wide and user-level configurations.
e. CI/CD and Infrastructure: The “.github” and “.woodpecker” directories contain configurations for automated testing, dependency management, and build pipelines—integral for maintaining a reliable, reproducible configuration.
f. Secrets: The “secrets” folder holds sensitive configuration data that might be included via secure mechanisms during deployments.

##### Relationships and Interactions
- The reusability of the modules is key: Machine-specific configurations in the “machines” directory import and reference modules from “modules” that implement boot settings, services, filesystems, etc.
- The “home-manager” configurations are applied to user environments independently but rely on a similar modular pattern to set up tools, applications, and user preferences.
- Custom package definitions in “pkgs” may be invoked by both system and user configurations.
- CI/CD pipelines (GitHub Actions and Woodpecker) are used to ensure that configuration changes are verified and built correctly, creating a feedback loop for system reliability.
- There is also an infrastructure for external documented resources (the README, and links to NixOS/Home Manager documentation) which informs the design approach.

##### Important Architectural Patterns and Design Principles
- Declarative Configuration: The project defines the state of systems through Nix expressions, ensuring reproducible setups.
- Modular Design: There is a clear separation of duties between machine-specific settings, reusable modules, user-level customizations, and package definitions.
- Layered Abstractions: The system builds atop a layered structure where base system configurations (modules) are extended by machine-level and user-level overlays.
- CI/CD Integration: Automated testing and dependency management pipelines ensure that changes are continuously integrated and deployed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Machines"
        MA["Machines: Configurations"]:::system
    end

    subgraph "Modules"
        MO["Modules: Reusable Modules (boot, common, services, hardware, filesystems, etc.)"]:::system
    end

    subgraph "Home Manager"
        HM["Home Manager: User Profiles and Modules"]:::operational
    end

    subgraph "Packages"
        PK["Packages: Custom Package Definitions and Themes"]:::system
    end

    subgraph "CI/CD"
        GH["GitHub Actions"]:::operational
        WD["Woodpecker"]:::operational
    end

    subgraph "Secrets"
        SC["Secrets: Sensitive Configuration Data"]:::operational
    end

    %% Relationships between components
    MA -->|"imports"| MO
    HM -->|"integrates"| MO
    MO -->|"invokes"| PK
    HM -->|"invokes"| PK

    GH -->|"builds"| MA
    GH -->|"builds"| MO
    GH -->|"builds"| HM
    GH -->|"builds"| PK

    WD -->|"builds"| MA
    WD -->|"builds"| MO
    WD -->|"builds"| HM
    WD -->|"builds"| PK

    SC -->|"provides"| MA
    SC -->|"provides"| HM

    %% Click Events
    click MA "https://github.com/alinkbetweennets/nix/tree/main/machines/"
    click MO "https://github.com/alinkbetweennets/nix/tree/main/modules/"
    click HM "https://github.com/alinkbetweennets/nix/tree/main/home-manager/"
    click PK "https://github.com/alinkbetweennets/nix/tree/main/pkgs/"
    click GH "https://github.com/alinkbetweennets/nix/tree/main/.github/"
    click WD "https://github.com/alinkbetweennets/nix/tree/main/.woodpecker/"
    click SC "https://github.com/alinkbetweennets/nix/tree/main/secrets/"

    %% Styles
    classDef system fill:#AED6F1,stroke:#036,stroke-width:2px;
    classDef operational fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
```
