ac846f4b03
Two stale-doc cleanups in one commit. Both surfaced during the post-Phase-B audit pass. 1. `docs/STRUCTURE.md` "Root Directory" listed three files that don't exist anywhere in the tree: - `GEMINI.md` (replaced long ago by `docs/AGENT.md`) - root-level `STRUCTURE.md` (this file actually lives in `docs/`) - `TODO.md` (long since replaced by `docs/ROADMAP.md`) Replaced with the actual root layout (flake.nix, flake.lock, README.md, .forgejo/, .githooks/) plus a `docs/` sub-tree that names every doc in the directory — the missing pieces the deleted bullets were trying to point at, now correctly located. 2. `docs/ROADMAP.md` Pillar 6 had three "Next" bullets that already shipped on 2026-04-26 (the welcome wizard, TROUBLESHOOTING.md, and the docs-index goal — README.md now links every doc in `docs/`). Moved all three to `(Shipped)`. Also rewrote the `nomarchy-manual` bullet — "orphaned reference today" was stale (the script is called from nomarchy-menu and nomarchy-theme-install per docs/SCRIPTS.md). The real remaining issue is its hardcoded `xdg-open https://learn.omacom.io/...` — an Omarchy URL that opens an unrelated upstream page when a user triggers the menu's Help entry. The bullet now names that specifically. No code touched; doc-only. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
141 lines
9.1 KiB
Markdown
141 lines
9.1 KiB
Markdown
# 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](#core-principles)
|
|
2. [Root Directory](#root-directory)
|
|
3. [The `core/` Directory (Foundational)](#the-core-directory-foundational)
|
|
4. [The `features/` Directory (Apps & Desktop)](#the-features-directory-apps--desktop)
|
|
5. [The `themes/` Directory (Dynamic Theming)](#the-themes-directory-dynamic-theming)
|
|
6. [The `lib/` Directory (Shared Library)](#the-lib-directory-shared-library)
|
|
7. [The `installer/` & `hosts/` Directories (Deployment)](#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
|
|
While the system is defined declaratively, Nomarchy uses a small, local state file (`~/.config/nomarchy/state.json`) to manage user preferences like the active theme, fonts, and feature toggles. This allows for instant UI feedback (via the `env-update` script) without requiring a full system rebuild for every cosmetic change.
|
|
|
|
---
|
|
|
|
## 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.
|
|
- **`.forgejo/workflows/`**: Forgejo Actions CI. Runs `nix flake check --no-build`, 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 in Forgejo and register a `forgejo-runner` (any Docker-capable Linux host works; 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`).
|
|
- **`behavior.nix`**: Deploys non-visual configs (Keybindings, Input settings, Window rules) with `lib.mkDefault`.
|
|
- **`configs.nix`**: Manages static configuration files and directories in `~/.config/`.
|
|
- **`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.
|