omnixient/modules/README.md

Modules Directory

The modules/ directory contains the modular NixOS configuration system that makes up Omnixient. Each module is responsible for a specific aspect of the system and can be enabled, disabled, or configured independently.

Module Architecture

Each module follows the standard NixOS module structure:

{ config, lib, pkgs, ... }:
with lib;
{
  options = {
    # Configuration options for this module
  };

  config = mkIf cfg.enable {
    # Module implementation
  };
}

Core System Modules

core.nix

Purpose: Base system settings and Omnixient-specific options What it configures:

• Essential system services (NetworkManager, Bluetooth, Audio)
• Graphics support (OpenGL/Vulkan)
• Font management
• Basic security settings
• Omnixient module system foundations

Key Features:

• Automatic hardware graphics detection
• Unified font configuration across the system
• Essential service enablement
• Module option definitions

packages.nix

Purpose: The always-installed base package set + fonts What it manages:

• Core utilities, file/network/archive tools, system monitoring
• Text processing, version control, shells, Nix tooling
• System + programming + icon fonts

The optional category bundles (development, multimedia, productivity, gaming) that used to live here have moved into opt-in packs under modules/packs/ — see the Opt-in packs section below and docs/packs.md. packages.nix now carries only the base set everyone gets.

services.nix

Purpose: System service configuration and management What it configures:

• Display manager (GDM)
• Audio system (PipeWire)
• Network services
• Container services (Docker, Podman)
• Development services (databases, etc.)

Service Categories:

• Desktop services (compositor, display manager)
• Audio/media services
• Network and connectivity
• Development and container services

users.nix

Purpose: User account management and configuration What it manages:

• User account creation and settings
• Shell configuration defaults
• User group memberships
• Home directory setup

Features:

• Automatic user creation based on configuration
• Shell preferences (zsh as default)
• Group membership for hardware access
• Integration with home-manager

Security and System

security.nix

Purpose: Security settings and authentication methods What it configures:

• Multi-factor authentication
• Fingerprint support (fprintd)
• FIDO2 security keys
• System hardening options
• Firewall configuration

Authentication Methods:

• Password authentication
• Fingerprint recognition
• FIDO2/WebAuthn security keys
• Two-factor authentication

boot.nix

Purpose: Boot system and kernel configuration What it manages:

• Boot loader configuration (systemd-boot)
• Kernel parameters and modules
• Plymouth boot theme
• Early boot optimizations

Boot Features:

• Fast boot configuration
• Kernel optimization
• Boot splash screen
• Hardware initialization

User Interface

menus.nix

Purpose: Application menus and launchers What it configures:

• Application launchers (rofi alternatives)
• Desktop menu systems
• Quick access interfaces
• Search functionality

walker.nix

Purpose: Walker application launcher configuration What it manages:

• Walker launcher settings
• Search backends and plugins
• Keybindings and interface
• Theme integration

fastfetch.nix

Purpose: System information display tool What it configures:

• System info formatting
• Logo and branding display
• Performance metrics
• Terminal integration

Development Environment

development.nix

Purpose: The richer dev module (shells, dev services, helper scripts) What it provides:

• Multiple language support (Rust, Go, Python, Node.js, C/C++)
• Language servers and tools
• Development containers and databases

Now gated on omni.packs.development.enable (not features.coding) and part of the development pack — see Opt-in packs. Imported by hosts via the pack, not by the ISO.

Language Support:

• Runtime environments
• Package managers
• Language-specific tools
• IDE and editor integration

scripts.nix

Purpose: Omnixient utility script management What it manages:

• System management scripts
• Theme switching utilities
• Development helper scripts
• Unix philosophy tools

Opt-in Packs

The packs/ subdirectory implements the core + opt-in goodies model: bundles of (packages + services + config) toggled with omni.packs.<name>.enable, always imported but inert until enabled. Packs are exposed as reusable flake.nixosModules.<pack> outputs, and the lnbits / aiolabs / bitcoin packs are standalone-importable onto a non-Omnixient NixOS.

Pack	Provides
media	players, image/video editing, screen capture, PDF
development	editors, LSPs, compilers, build tools, container CLIs, development.nix
gaming	Steam, Lutris, Wine, performance tools
office	browsers, comms, office suites, notes, backup
containers	Docker + Podman (unified)
lnbits	the LNbits dev environment (dev-env)
aiolabs	aiolabs projects/deploy/tmux, on top of lnbits
bitcoin	a real bitcoind + lightning node via nix-bitcoin (opt-in import)

Legacy omni.preset / omni.features.* still work — they drive packs via packs/compat.nix. Full guide: modules/packs/README.md and docs/packs.md.

Hardware Support

The hardware/ subdirectory contains hardware-specific modules:

default.nix

Purpose: Hardware detection and automatic configuration What it does:

• Detects available hardware
• Enables appropriate drivers
• Configures hardware-specific settings
• Imports relevant hardware modules

GPU Support

• amd.nix: AMD GPU drivers and configuration
• intel.nix: Intel integrated graphics
• nvidia.nix: NVIDIA proprietary drivers

Audio and Input

• audio.nix: Audio system configuration
• touchpad.nix: Laptop touchpad settings
• bluetooth.nix: Bluetooth device support

Theme System

The themes/ subdirectory contains complete theme definitions:

Each theme module (e.g., tokyo-night.nix) configures:

• Color palette definitions
• Terminal color schemes
• Editor themes (Neovim, VSCode)
• Desktop component theming (Waybar, Hyprland)
• GTK/Qt application themes

Desktop Environment

The desktop/ subdirectory contains desktop-specific configurations:

hyprland.nix

Purpose: Hyprland compositor configuration Sub-modules:

• bindings.nix: Keyboard shortcuts and bindings
• autostart.nix: Applications started with the desktop
• idle.nix: Idle management and screen locking

Utility Modules

lib.nix

Purpose: Shared library functions and utilities What it provides:

• Helper functions used across modules
• Common configuration patterns
• Utility functions for theme and configuration management

colors.nix

Purpose: Color management and palette definitions What it manages:

• Color space conversions
• Palette generation utilities
• Theme color validation

helpers.nix

Purpose: Additional helper functions What it provides:

• File and directory utilities
• Configuration templating functions
• System integration helpers

Module Dependencies

core.nix (foundation)
    ↓
packages.nix + services.nix (system layer)
    ↓
security.nix + boot.nix (system hardening)
    ↓
themes/*.nix (visual layer)
    ↓
desktop/*.nix (user interface)
    ↓
development.nix (developer tools)

Adding New Modules

To add a new module:

1. Create the module file in the appropriate subdirectory
2. Follow the standard NixOS module structure
3. Define clear options with types and descriptions
4. Import the module in configuration.nix
5. Document the module's purpose and options
6. Test the module in isolation and with others

Module Best Practices

1. Single Responsibility: Each module handles one aspect
2. Clear Options: Well-defined configuration interface
3. Documentation: Comments and option descriptions
4. Dependencies: Explicit module dependencies
5. Testing: Verify module works in isolation
6. Performance: Efficient evaluation and build times

This modular architecture makes Omnixient highly customizable while maintaining clean separation of concerns.