Files

Bernardo Magri 29cc0d2547 feat: implement modular foundation and core system services

- Update flake.nix with 25.11 release and core inputs
- Add dedicated modules for audio (Pipewire), bluetooth, and networking
- Update GEMINI.md with the new Modular Merging Architecture blueprint
- Configure graphical installer ISO and test VM outputs

2026-04-03 21:06:42 +01:00

3.2 KiB

Raw Blame History

Nomarchy - A NixOS-based distribution with Omarchy flavour - Agent Build Blueprint

System Architecture Overview

Nomarchy uses a Modular Merging Architecture. The distro is distributed as a Nix Flake that exports two primary modules: nixosModules.system and nixosModules.home. This approach ensures strict separation between the "Upstream" core and the "Downstream" user configuration.

Users interact with the system by importing the distro's modules into their own flake.nix and then layering their own personal modules (system.nix and home.nix) on top. This follows the native NixOS design pattern for declarative, multi-module systems.

Directory Structure

flake.nix (Master entry point with core modules and test configurations)
installer/install-nomarchy.sh (Interactive installer generating a clean downstream flake)
modules/system/default.nix (Distro-wide OS defaults: SDDM, Plymouth, Audio, Network)
modules/home/default.nix (Distro-wide user environment: Hyprland, Waybar, Styling)
bin/ (The collection of Omarchy productivity and config scripts)
themes/ (Distro-wide color palettes and backgrounds)

Core Components & Logic

1. Separation of Concerns (Upstream vs. Downstream)

Upstream: The nomarchy/ directory contains the core logic. It is treated as an immutable input by the target system.
Downstream: The user's /etc/nixos/flake.nix imports the upstream modules. The user's personal customizations are kept in /etc/nixos/system.nix and /etc/nixos/home.nix.
Merging: NixOS automatically merges definitions. For example, if both the distro and the user add packages to home.packages, the final system includes the union of both lists.

2. The Interactive Installer (`installer/install-nomarchy.sh`)

The installer is designed to bootstrap a fresh system with this modular structure:

Repo Detection: Identifies the location of the Nomarchy source.
Scaffolding: Creates a new downstream flake.nix that imports Nomarchy core modules.
User Files: Generates skeleton system.nix and home.nix files for the user to customize.
Bundling: Copies the entire Nomarchy source to /etc/nixos/nomarchy so the system can be rebuilt offline.

3. Home Manager Integration

Hybrid Declarative State: While the distro is declarative, it uses state files in ~/.config/home-manager/ (managed by the distro's scripts) to allow for instant UI feedback (theming, fonts, wallpapers) without needing a full system rebuild for every small tweak.
Script Wrapping: All scripts in bin/ are wrapped with their specific dependencies (swayosd, pulseaudio, jq, etc.) to ensure they work reliably across different hardware.

4. Dynamic Theming

Palettes: Themes are defined in simple colors.toml files. The distro dynamically generates Base16 palettes from these, allowing for infinite theme expansion without modifying Nix code.

Verification & Build

Test Installer: ./bin/nomarchy-test-installer (Builds a VM of the installer environment).
Check Integrity: nix flake check --impure (Verifies all configurations evaluate).
Build ISO: nix build .#nixosConfigurations.installerIso.config.system.build.isoImage (Generates the flashable USB image).

3.2 KiB Raw Blame History