omnixy/ROOT_FILES.md

Root Directory Files

This document explains the purpose of each file in the root directory of the OmniXY repository.

Configuration Files

flake.nix

Purpose: Main Nix flake definition

• Defines all external dependencies (inputs)
• Exports system configurations, packages, and development shells
• Contains the core logic for building OmniXY
• Manages reproducible builds through flake.lock

Key Sections:

• inputs: External dependencies (nixpkgs, home-manager, hyprland, etc.)
• outputs: NixOS configuration, packages, development shells, apps
• nixosConfigurations.omnixy: Main system configuration
• devShells: Language-specific development environments
• packages: Custom OmniXY utilities and tools
• apps: Executable applications (installer)

configuration.nix

Purpose: Main NixOS system configuration entry point

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

What it does:

• Enables essential system services
• Imports modular configurations from modules/
• Sets the active theme (controls entire system appearance)
• Defines system users and permissions
• Configures boot settings and hardware

home.nix

Purpose: Home Manager configuration for user environment

• Manages user-specific packages and settings
• Configures dotfiles and application preferences
• Handles user services and desktop environment
• Integrates with the theme system

What it manages:

• User package installations
• Shell configuration (zsh, bash)
• Git configuration and tools
• Development environment settings
• Application configurations that run as user

flake.lock

Purpose: Lock file for reproducible builds

• Pins exact versions of all dependencies
• Ensures identical builds across different machines
• Generated automatically by Nix
• Should be committed to version control

hardware-configuration.nix

Purpose: Hardware-specific NixOS configuration

• Generated by nixos-generate-config
• Contains machine-specific settings
• Defines boot loader, filesystems, and kernel modules
• Should be customized per installation

Generated content:

• Filesystem mount points
• Boot loader configuration
• Hardware-specific kernel modules
• Network interface settings

Installation Files

install.sh

Purpose: Interactive, styled installer script

• Beautiful terminal UI with colors and animations
• Guides users through complete installation process
• Handles system verification, backup, and configuration
• Includes theme selection and feature configuration

Features:

• System requirements checking
• Automatic configuration backup
• User account setup
• Theme selection interface
• Feature toggles (fingerprint, gaming, etc.)
• System building with progress indication

install-simple.sh

Purpose: Unix philosophy compliant installer

• Command-line arguments instead of interactive prompts
• Scriptable and automatable
• Clean, pipeable output
• Follows "do one thing well" principle

Usage:

./install-simple.sh --user alice --theme gruvbox --quiet

Options:

• --user: Set username
• --theme: Select theme
• --quiet: Minimal output
• --dry-run: Test without applying changes

boot.sh

Purpose: Bootstrap script for fresh NixOS installations

• Downloads OmniXY from GitHub
• Minimal dependencies (just bash and basic tools)
• Runs the full installer automatically
• Can be executed via curl pipe

What it does:

1. Verifies NixOS installation
2. Installs git if needed
3. Clones the OmniXY repository
4. Executes the main installer

Documentation Files

README.md

Purpose: Main project documentation and introduction

• Project overview and features
• Installation instructions
• Usage examples and configuration
• Contributing guidelines and links

CLAUDE.md

Purpose: Instructions for Claude Code AI assistant

• Development workflow documentation
• Command references and examples
• Architecture explanations
• Best practices and conventions

LICENSE

Purpose: Legal license for the project

• Defines usage rights and restrictions
• Currently MIT License
• Applies to all code in the repository

Asset Files

logo.svg / logo.txt

Purpose: OmniXY project logos

• SVG vector logo for web/documentation
• ASCII art logo for terminal display
• Used in installers and documentation

icon.png / icon.txt

Purpose: Project icons

• PNG icon for applications and desktop
• ASCII icon for terminal contexts

Development Files

*.qcow2 files (if present)

Purpose: Virtual machine disk images

• Pre-built OmniXY system images for testing
• Used for development and demonstration
• Can be run with QEMU/KVM

File Organization Principles

1. Configuration First: Core system files at root level
2. Clear Naming: Descriptive filenames indicate purpose
3. Separation of Concerns: Different aspects in separate files
4. Documentation: Every major file documented
5. Reproducibility: All build inputs tracked and versioned

Relationship Between Files

flake.nix
    ↓ (imports)
configuration.nix
    ↓ (imports)
modules/*.nix
    ↓ (configures)
System Services & Packages

home.nix
    ↓ (configures)
User Environment & Dotfiles

install.sh / install-simple.sh
    ↓ (copies and configures)
All Configuration Files
    ↓ (builds)
Complete OmniXY System

This structure provides a clear separation between system configuration, user environment, installation tooling, and documentation, making the project maintainable and understandable.