Nomarchy/docs/STRUCTURE.md

Nomarchy - Architecture & Directory Structure

Nomarchy is a NixOS-based distribution characterized by its Modular Merging Architecture. This design strictly separates the "Upstream" core (the distro's logic) from the "Downstream" configuration (the user's personal setup), while allowing for dynamic, state-based theming and a highly modular desktop environment.

Table of Contents

1. Core Principles
2. Root Directory
3. The core/ Directory (Foundational)
4. The features/ Directory (Apps & Desktop)
5. The themes/ Directory (Dynamic Theming)
6. The lib/ Directory (Shared Library)
7. The installer/ & hosts/ Directories (Deployment)

---

Core Principles

Upstream vs. Downstream

• Upstream: The code in this repository is treated as the "Upstream" source. It provides the base OS configurations, dynamic theming engine, and modular application logic.
• Downstream: A user's installation (typically in /etc/nixos/) imports the Upstream flake. The user layers their own system.nix and home.nix on top, overriding or extending the Upstream settings using native NixOS lib.mkDefault and lib.mkForce patterns.

Hybrid Declarative State

Nomarchy balances the ease of a GUI with the power of declarative configuration.

• Runtime Discovery: Local state files (~/.config/nomarchy/state.json and /etc/nixos/state.json) handle personal choices like theme, font, and UI toggles. Changes made via the Theme Picker or Welcome Wizard update these files and provide instant visual feedback (via the env-update script).
• Declarative Persistence: To ensure these choices are permanent and reproducible, the nomarchy-state-sync-nix script automatically mirrors the home-side configuration into /etc/nixos/nomarchy-state.nix. This file is imported by the user's home.nix.
• Solidification: When you run nomarchy-env-update, your current runtime state is "solidified" into the Nix configuration, preventing your settings from reverting to defaults during the next full system rebuild.

---

Root Directory

• flake.nix: The master entry point for the entire distribution.
  • Inputs: Defines external dependencies like nixpkgs, home-manager, disko, stylix, and others.
  • Outputs:
    • nixosModules.system: Exports the foundational OS logic (./core).
    • nixosModules.home: Exports the application and desktop logic (./features).
    • nixosConfigurations: Defines pre-configured targets like nomarchy-installer, nomarchy-live, and a testing vm.
• flake.lock: Locks dependency versions for reproducible builds.
• README.md: Project overview, installation instructions, and basic usage.
• docs/: All long-form documentation. Key entry points:
  • AGENT.md: Onboarding for AI coding agents picking up Nomarchy.
  • STRUCTURE.md: (This file) Detailed architectural documentation.
  • OPTIONS.md: Reference for every nomarchy.* option.
  • ROADMAP.md: Now / Next / Later board and the Shipped log.
  • MIGRATION.md: Layering Nomarchy onto an existing NixOS install.
  • KEYBINDINGS.md: Auto-generated keybinding reference.
  • SCRIPTS.md: Auto-generated nomarchy-* script audit.
  • TROUBLESHOOTING.md: Common rebuild errors and fixes.
  • creating-themes.md: Theme palette authoring guide.
• .gitea/workflows/: Gitea/Forgejo Actions CI (the .gitea/ path is scanned by both Gitea and Forgejo; .forgejo/ is not scanned by Gitea). Runs nix flake check --no-build, the opt-in toggle eval matrix (bin/utils/nomarchy-eval-matrix), lints every nomarchy-* bash script with bash -n + shellcheck --severity=error, and verifies docs/SCRIPTS.md is up to date on every push to main and every PR. To activate: enable Actions on the repo and register an act_runner (any Docker-capable Linux host works — including the Gitea server itself; the workflow uses ubuntu-latest and installs Nix itself).
• .githooks/: Optional per-clone git hooks (pre-commit lints changed scripts and regenerates docs/SCRIPTS.md). Enable with git config core.hooksPath .githooks. CI enforces the same invariants tree-wide.

---

The core/ Directory (Foundational)

The core/ directory contains the foundational modules required for a functional system and user environment.

core/system/ (OS-Level)

• default.nix: The central entry point for the system module, importing all OS components.
• options.nix: Defines the nomarchy.system configuration options (e.g., DNS, Timezone, Feature toggles).
• state.nix: Loads and applies the system-level state (from /etc/nixos/state.json).
• audio.nix: Configures Pipewire, Wireplumber, and audio-related settings.
• bluetooth.nix: Bluetooth stack and management tools.
• browser.nix: System-level browser configurations and protocols.
• network.nix: NetworkManager configuration, DNS optimization, and Wi-Fi powersave settings.
• hardware.nix: Generic hardware support and hardware-specific script triggers.
• virtualization.nix: Libvirtd, Docker, and VM guest support.
• impermanence.nix: Root-on-RAM/Impermanence setup for ephemeral root filesystems.
• scripts/: A collection of low-level system scripts (e.g., nomarchy-hw-match, nomarchy-setup-dns).

core/home/ (User-Level)

• default.nix: The entry point for the base Home Manager module.
• options.nix: Defines the nomarchy user options (Toggles, Theme, Fonts, etc.).
• state.nix: Loads and applies user-level state (from ~/.config/nomarchy/state.json).
• overrides.nix: Declares nomarchy.overrides.* (reserved for a future file-based override loader; currently no-op).
• configs.nix: Manages static configuration files and directories in ~/.config/. Honors nomarchy.configOverrides as a bulk redirect to a replacement config dir.
• bash.nix: Shell environment, aliases, and specialized env-update hooks.
• security.nix: Polkit, keyring management, and GPG settings.
• config/: Contains the physical source files for the base user configuration (e.g., starship.toml, hypr/ behavior configs).

---

The features/ Directory (Apps & Desktop)

The features/ directory contains optional, modular components that define the user's interactive environment.

• default.nix: Aggregates and enables all sub-modules in features/.
• apps/: Individual application modules.
  • Each app (e.g., alacritty, btop, vscode, ghostty) has its own directory containing a default.nix and a config/ subdirectory.
  • Apps are configured using the "Individual File Management" pattern to avoid directory symlink conflicts with the theme loader.
• desktop/: The graphical environment core.
  • hyprland/: The primary tiling window manager configuration.
  • waybar/: The status bar configuration, including dynamic CSS generation.
  • idle.nix & nightlight.nix: Management of screen timeouts and blue light filters.
• scripts/: High-level utility scripts (e.g., nomarchy-update, nomarchy-theme-set).
  • utils/: Helper scripts like nomarchy-launch-or-focus-tui or nomarchy-restart-*.

---

The themes/ Directory (Dynamic Theming)

The theming system is the "soul" of Nomarchy, providing dynamic, consistent aesthetics across all applications.

themes/engine/ (The Logic)

• loader.nix: The core theme loader. It reads the active theme from state and selectively deploys app-specific themed configs (e.g., btop.theme, kitty.conf) to ~/.config/.
• stylix.nix: Integration with Stylix for base color palette and wallpaper management.
• plymouth.nix & sddm.nix: System-level theming for the boot screen and login manager.

themes/palettes/ (The Data)

• Contains subdirectories for every available theme (e.g., summer-night, nord, tokyo-night).
• Each theme directory includes:
  • colors.toml: The Base16 color definition.
  • backgrounds/: A collection of theme-aware wallpapers.
  • apps/: Themed overrides for specific applications (e.g., btop.theme, vscode.json).

themes/templates/ (The Blueprints)

• Contains .tpl files (e.g., waybar.css.tpl, hyprland.conf.tpl) used to generate dynamic configuration files that incorporate the current theme's color palette.

---

The lib/ Directory (Shared Library)

The lib/ directory provides centralized logic and data structures to maintain consistency.

• default.nix: A shared Nix library providing helper functions:
  • readState: Safely reads JSON/text state files.
  • getPalette / getColorScheme: Resolves theme names to color data.
  • resolveWallpaper: Logic for choosing the correct background image.
  • getIconsTheme: Resolves the appropriate icon set for a theme.
• state-schema.nix: Defines the single source of truth for the shape and default values of the Nomarchy state (both system and home).

---

The installer/ & hosts/ Directories (Deployment)

installer/ (Bootstrap)

• install.sh: The interactive TTY-based installer. It handles disk partitioning, NixOS installation, and generating a clean "Downstream" flake for the user.
• disko-config.nix: The disko partition layout (BTRFS on top of LUKS2). A Nix function of { mainDrive, extraDrives ? [] } — single-disk path is extraDrives = []; multi-disk adds BTRFS -d single -m raid1 across the extras. Invoked by install.sh via disko --argstr mainDrive … --arg extraDrives '[…]'.

hosts/ (Targets)

• nomarchy-installer.nix: Configuration for the minimal, TTY-based installation ISO.
• nomarchy-live.nix: Configuration for the full graphical live environment, used for testing and GUI-based installation.