29cc0d2547
- 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
41 lines
3.2 KiB
Markdown
41 lines
3.2 KiB
Markdown
# 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:
|
|
1. **Repo Detection:** Identifies the location of the Nomarchy source.
|
|
2. **Scaffolding:** Creates a new downstream `flake.nix` that imports Nomarchy core modules.
|
|
3. **User Files:** Generates skeleton `system.nix` and `home.nix` files for the user to customize.
|
|
4. **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).
|