omnixy/docs/ARCHITECTURE.md

OmniXY Architecture

Overview

OmniXY is built on a layered architecture that combines NixOS's declarative system configuration with modern desktop tools and development environments.

System Layers

┌─────────────────────────────────────────┐
│             User Interface              │
│    Hyprland + Waybar + Applications     │
├─────────────────────────────────────────┤
│           Desktop Environment           │
│   Theme System + Window Management      │
├─────────────────────────────────────────┤
│          OmniXY Configuration           │
│     Modules + Scripts + Packages        │
├─────────────────────────────────────────┤
│          Home Manager Layer             │
│      User Environment & Dotfiles        │
├─────────────────────────────────────────┤
│             NixOS System                │
│    Package Management + Services        │
├─────────────────────────────────────────┤
│             Linux Kernel                │
│        Hardware Abstraction             │
└─────────────────────────────────────────┘

Core Components

1. Nix Flake System (flake.nix)

The foundation that defines all system inputs and outputs:

• Inputs: External dependencies (nixpkgs, home-manager, hyprland)
• Outputs: System configurations, packages, development shells, apps
• Lock File: Ensures reproducible builds across machines

2. System Configuration (configuration.nix)

Main NixOS system configuration that:

• Imports all modules
• Defines system-wide settings
• Sets the current theme
• Configures hardware and services

3. Module System (modules/)

Modular architecture with focused components:

• Core: Base system settings and OmniXY options
• Themes: Complete color schemes and application theming
• Hardware: Device-specific configurations
• Desktop: Window manager and GUI settings
• Development: Programming tools and environments

4. Home Manager (home.nix)

User environment management:

• User-specific packages
• Dotfile configuration
• Application settings
• Theme integration

5. Package System (packages/)

Custom Nix packages:

• OmniXY utility scripts
• Specialized tools
• Theme packages

6. Unix Tools (scripts/)

Focused utilities following Unix philosophy:

• System management
• Configuration backup
• User setup
• Build automation

Data Flow

System Build Process

flake.nix → configuration.nix → modules/*.nix → system build
    ↓              ↓                 ↓
 inputs        system opts      module config
    ↓              ↓                 ↓
nixpkgs       theme selection   packages/services

Theme Application Flow

Theme Selection → Module Configuration → Application Settings
      ↓                    ↓                      ↓
  omnixy theme      modules/themes/        GTK/Qt/Terminal
   set <name>         <name>.nix              theming

User Environment Flow

home.nix → Home Manager → User Packages & Dotfiles
    ↓           ↓                 ↓
user config  evaluation     ~/.config/* files

Configuration Management

Declarative Configuration

• All system state defined in Nix expressions
• No imperative commands modify system configuration
• Changes require rebuild to take effect

Immutable System

• Built configurations are immutable
• Previous generations available for rollback
• Atomic upgrades prevent partial failures

Module Composition

• Features implemented as independent modules
• Modules can depend on other modules
• Options system provides configuration interface

Reproducible Builds

• Flake inputs pinned with lock file
• Same inputs produce identical outputs
• Cross-machine consistency guaranteed

Development Architecture

Language Support

Each language environment includes:

• Runtime and tools
• Language server protocols (LSPs)
• Package managers
• Development utilities

Shell Environments

Development Shell:
  nix develop .#<language>
       ↓
  Language-specific packages
       ↓
  Configured environment

Tool Integration

• Git with lazygit TUI
• Terminal with shell integration
• Editor with language support
• Build systems and debuggers

Theme Architecture

Unified Theming

All applications themed consistently:

• Terminal emulators (Alacritty, Kitty)
• Text editors (Neovim, VSCode)
• Desktop components (Waybar, Hyprland)
• GUI applications (GTK, Qt)

Color Management

Theme Module → Color Variables → Application Configs
     ↓               ↓                    ↓
tokyo-night.nix → #7aa2f7 (blue) → terminal.colors.blue

Theme Switching

1. Update configuration.nix with new theme
2. Rebuild system to apply changes
3. All applications automatically use new theme

Hardware Support

Adaptive Configuration

• Automatic hardware detection
• GPU-specific optimizations (Intel, AMD, NVIDIA)
• Audio system configuration
• Network and Bluetooth setup

Conditional Modules

config = lib.mkIf cfg.hardware.nvidia.enable {
  # NVIDIA-specific configuration
};

Security Architecture

System Security

• Secure boot support
• Firewall configuration
• AppArmor profiles
• User isolation

Authentication

• Multi-factor authentication support
• Fingerprint integration
• FIDO2 security keys
• Password management

Extensibility

Custom Modules

• Follow NixOS module structure
• Use options for configuration
• Implement proper dependencies
• Document all options

Package Development

• Custom packages in packages/
• Integration with flake outputs
• Proper meta information
• Cross-platform support

Theme Development

• Color palette definition
• Application configuration
• Testing across components
• Documentation and examples

This architecture provides a solid foundation for a reproducible, customizable, and maintainable desktop Linux system.