# 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**:
```bash
./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.