documentation

2025-09-25 07:50:48 -07:00
parent 85e493eb54
commit d8947e67b7
41 changed files with 4405 additions and 538 deletions
--- a/ROOT_FILES.md
+++ b/ROOT_FILES.md
@@ -0,0 +1,191 @@
+# 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.