2.Working Model

Working Model

This page explains the data flow and working model of Nucleus using the minimal template as the reference implementation. Since both the GNOME and KDE templates are built on top of the minimal template, the core data flow model remains consistent across all templates.

Schematic Diagrams: Nucleus Internals

The following schematic diagrams explains the core internals nucleus via the minimal starter in different scenarios. Understanding it is a pre-requisite because all of the included starters are built on top of minimal starter. The diagram is also crucial for you to understand because probably your future configuration will also be built on top of one of the included starter. The root flake.nix per starter serves as logical control center that treats every host as an organelle.

Minimal Single Host

graph LR
    A["flake.nix"]
    B["modules/"] -.-> B1["common/"]
    B -.-> B2["features/"]
    B -.-> B3["hosts/"]
    B1 -.-> B11["nixos-core/"]
    B1 -.-> B12["disko/"]
    B2 -.-> B21["home-manager/"]
    B2 -.-> B22["workstation/"]
    B3 -.-> B30["DESIRED_HOSTNAME"]

    C["nixosConfigurations.DESIRED_HOSTNAME"]

    B11 --> C 
    B12 --> C 
    B21 --> C 
    B22 --> C
    B30 --> C

    C ==> A

Loading

Minimal Multi Host

graph LR
    A["flake.nix"]
    B["modules/"] -.-> B1["common/"]
    B -.-> B2["features/"]
    B -.-> B3["hosts/"]
    B1 -.-> B11["nixos-core/"]
    B1 -.-> B12["disko/"]
    B1 -.-> B13["*overlays/"]
    B2 -.-> B21["home-manager/"]
    B2 -.-> B22["workstation/"]
    B2 -.-> B23["*virtualisation/"]
    B3 -.-> B30["DESIRED_HOSTNAME"]
    B3 -.-> B31["ANOTHER_DESIRED_HOSTNAME"]
    B3 -.-> B32["YET_ANOTHER_DESIRED_HOSTNAME"]

    C["nixosConfigurations.DESIRED_HOSTNAME"]
    D["nixosConfigurations.ANOTHER_DESIRED_HOSTNAME"]
    E["nixosConfigurations.YET_ANOTHER_DESIRED_HOSTNAME"]

    B11 -.-> D
    B12 -.-> D
    B21 -.-> D
    B22 -.-> D
    B31 -.-> D


    B11 --> C
    B12 --> C
    B21 --> C
    B22 --> C
    B30 --> C


    B11 --x E
    B12 --x E
    B13 --x E
    B22 --x E
    B23 --x E
    B32 --x E

    D ~~~ C
    D ~~~ E
    B13 ~~~ Z["*X means X is not provided"]

    C ==> A
    D ==> A
    E ==> A

Loading

General Explanation

According to the above diagrams, the general explanation that covers both cases i-e single host and multi host environments. The nucleus builds on 3 big unwrapped submodules found in the modules/ directory.

1. common/ —— directory that contains re-usable parts that is almost required by every host.
2. features/ —— directory that contains re-usable parts whose inclusion per host is up to your choice.
3. hosts/ —— directory that contains host definition and its specific settings so that nothing is contaminated with mixed decisions.

The nodes DESIRED_HOSTNAME, ANOTHER_DESIRED_HOSTNAME and YET_ANOTHER_DESIRED_HOSTNAME are host names of your machines and are separate directories that contains hosts specific settings its general configuration.

nixosConfigurations.DESIRED_HOSTNAME = ... is where you tie features with a specific host whose hostname is DESIRED_HOSTNAME. The data defined in let ... in inside flake.nix is passed down through every feature and common configuration if they needs/expects it for internal use.

Why This Model Works

1. Modularity - Each layer has a single responsibility
2. Reusability - Common features don't require duplication across machines
3. Flexibility - Hosts can selectively enable/disable features from flake.nix
4. Maintainability - Clear hierarchy makes debugging straightforward
5. Scalability - Can support multiple machines without exponential complexity
6. Declarativity - Entire system is described in Nix code, no imperative steps