diff --git a/STRUCTURE.md b/STRUCTURE.md new file mode 100644 index 0000000..0618a12 --- /dev/null +++ b/STRUCTURE.md @@ -0,0 +1,133 @@ +# 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 `installerIso`, `live-iso`, and a testing `vm`. +- **`flake.lock`**: Locks dependency versions for reproducible builds. +- **`GEMINI.md`**: Foundational mandates and architectural rules for the Nomarchy Agent. +- **`STRUCTURE.md`**: (This file) Detailed architectural documentation. +- **`README.md`**: Project overview, installation instructions, and basic usage. +- **`TODO.md`**: Roadmap and pending tasks. + +--- + +## 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. +- **`switcher.nix`**: Provides the `nomarchy-theme-selector` and `nomarchy-wallpaper-selector` tools. +- **`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-golden.nix`**: The standard partition layout (BTRFS on top of LUKS2). +- **`disko-btrfs-luks.nix`**: A simpler reference layout for disk management. + +### `hosts/` (Targets) +- **`installer-iso.nix`**: Configuration for the minimal, TTY-based installation ISO. +- **`live-iso.nix`**: Configuration for the full graphical live environment, used for testing and GUI-based installation.