███╗   ██╗██╗██╗  ██╗ ██████╗ ███████╗    ██████╗ ██████╗ ███╗   ██╗███████╗██╗ ██████╗ 
████╗  ██║██║╚██╗██╔╝██╔═══██╗██╔════╝   ██╔════╝██╔═══██╗████╗  ██║██╔════╝██║██╔════╝ 
██╔██╗ ██║██║ ╚███╔╝ ██║   ██║███████╗   ██║     ██║   ██║██╔██╗ ██║█████╗  ██║██║  ███╗
██║╚██╗██║██║ ██╔██╗ ██║   ██║╚════██║   ██║     ██║   ██║██║╚██╗██║██╔══╝  ██║██║   ██║
██║ ╚████║██║██╔╝ ██╗╚██████╔╝███████║   ╚██████╗╚██████╔╝██║ ╚████║██║     ██║╚██████╔╝
╚═╝  ╚═══╝╚═╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝    ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝     ╚═╝ ╚═════╝ 

📖 Table of Contents

• ✨ Highlights
• 🚀 Quick Start
• 📊 Project Statistics
• 🏗️ Architecture
• 🎯 Key Features
• 🗂️ Module Categories
• 🔧 Development Workflow
• 🎮 Gaming Setup
• 🌐 Hyprland Configuration
• 🛠️ Custom Packages
• 📚 Documentation
• 🤝 Contributing

✨ Highlights

[!TIP] New to NixOS? Check out the docs index for a comprehensive guide!

🎯 What makes this configuration special:

• 🚄 Blazingly Fast Builds - Optimized evaluation with module archiving
• 🎮 Gaming-First Design - CPU isolation, low-latency optimizations, VRR support
• 🔧 Developer Paradise - Multi-language support (Rust, C++, Haskell, Python), AI tools
• 🎨 Beautiful Hyprland - 18 workspaces, 8 scratchpads, custom Quickshell panel
• 📦 30 Custom Packages - Tailored tools for productivity and performance
• 🧩 Modular Architecture - 27 domain modules with feature flags, 502 Nix files
• 🔄 Local Gates - pre-commit hook (just lint) plus nix flake check -L; no CI service runs this repo

🚀 Quick Start

# 1️⃣ Clone the repository
git clone https://github.com/neg-serg/nixos-config /etc/nixos
cd /etc/nixos

# 2️⃣ Build and switch (with flakes)
sudo nixos-rebuild switch --flake .#trantor

# 3️⃣ Or use the helper (if zcli is enabled)
nh os switch

[!NOTE] Replace trantor with your hostname if you're setting up a different machine.

📊 Project Statistics

📈 By The Numbers

📁 Category	🔢 Count	📊 Progress
Module Domains	27
Nix Files	502
Custom Packages	107
Module Files	319

| Total Commits | 3200+ | |

🏗️ Architecture

graph TB
    subgraph "🎯 Entry Point"
        A[flake.nix]
    end
    
    subgraph "🖥️ Host Configuration"
        B[hosts/trantor]
    end
    
    subgraph "📦 System Modules"
        C[modules/features]
        D[modules/cli]
        E[modules/dev]
        F[modules/user]
        G[modules/servers]
    end
    
    subgraph "👤 User Configuration"
        H[modules/user/nix-maid]
        I[Hyprland Config]
        J[Quickshell Panel]
    end
    
    subgraph "🎁 Custom Packages"
        K[packages/overlay]
        L[Game Launchers]
        M[Productivity Tools]
    end
    
    A --> B
    B --> C
    B --> D
    B --> E
    B --> F
    B --> G
    H --> I
    H --> J
    C -.feature flags.-> D
    C -.feature flags.-> E
    K --> L
    K --> M
    
    style A fill:#5277C3,color:#fff
    style B fill:#00D9FF,color:#000
    style H fill:#FF6B35,color:#fff
    style K fill:#4CAF50,color:#fff

🔄 Build Flow

flowchart LR
    A[📝 Edit Config] --> B{🔍 Pre-commit + flake check}
    B -->|✅ Pass| C[🎨 Format]
    B -->|❌ Fail| A
    C --> D[🔎 Lint]
    D --> E[🏗️ Build]
    E --> F{🧪 Test}
    F -->|✅| G[🚀 Deploy]
    F -->|❌| A
    
    style A fill:#5277C3,color:#fff
    style G fill:#4CAF50,color:#fff
    style B fill:#FF9800,color:#fff
    style F fill:#FF9800,color:#fff

🎯 Key Features

🗂️ Repository Structure

📦 nixos-config/
├── 📄 flake.nix                      # 🎯 Flake entry point
├── 📂 hosts/                         # 🖥️ Host configurations
│   └── 📁 trantor/                    # Primary workstation
│       ├── hardware.nix
│       ├── networking.nix
│       └── services/                # policy.nix, vpn.nix, telegram-units.nix, telegram/*.py
├── 📂 modules/                       # 🧩 System modules (27 domains)
│   ├── 📁 features/                  # ⚙️ Feature flags (16 files)
│   │   ├── core.nix                 # Core feature options
│   │   ├── gui.nix                  # GUI stack options
│   │   ├── dev.nix                  # Development tools
│   │   └── ...
│   ├── 📁 cli/                       # 💻 CLI tools (10 files)
│   │   ├── tools.nix                # 28 packages
│   │   ├── dev.nix                  # Git, encoding, fetch
│   │   └── ...
│   ├── 📁 user/nix-maid/             # 👤 User configuration
│   │   ├── 📁 hyprland/              # 🌊 Hyprland (4 modules)
│   │   │   ├── main.nix
│   │   │   ├── environment.nix
│   │   │   ├── files.nix
│   │   │   ├── services.nix
│   │   │   └── ...                  # workspaces live in files/gui/hypr/hyprland.lua
│   │   └── ...
│   ├── 📁 servers/                   # 🖧 Server services
│   └── ...
├── 📂 packages/                      # 🎁 Custom overlays (30)
│   ├── game/
│   ├── rmpc/
│   └── ...
├── 📂 files/                         # 📝 Config files
│   ├── 📁 gui/hypr/                  # Hyprland configs
│   ├── 📁 quickshell/                # Panel configuration
├── 📂 scripts/dev/                   # 🔧 Dev & CI scripts
├── 📂 docs/                          # 📚 Documentation (index, howto/, runbook-*.md)

🗂️ Module Categories

pie title Module Categories Distribution
    "System (8)" : 8
    "Desktop/GUI (12)" : 12
    "Development (6)" : 6
    "Web & Comm (4)" : 4
    "Core (16)" : 16
    "Servers (7)" : 7
    "Other (9)" : 9

🔧 Development Workflow

🏃 Quick Commands

# 🐚 Enter development shell with all tools
nix develop

# 🎨 Format all code (nixfmt/treefmt)
just fmt

# 🔍 Run all checks (format + lint + build)
just check

# 🏗️ Build without switching
nixos-rebuild build --flake .#trantor

# 🚀 Rebuild and switch
just deploy

# 🪝 Enable repo git hooks (lint + commit-msg scope check)
just hooks-enable

🔄 Local Gates (no CI service)

[!IMPORTANT] Changes are validated by the pre-commit hook (just lint) and nix flake check -L

graph LR
    A[📝 Commit] --> B[🎨 Format Check]
    B --> C[🔎 Lint Check]
    C --> D[🧪 Build Test]
    D --> E[✅ NixOS Eval]
    E --> F[🎯 Custom Checks]
    F --> G{All Pass?}
    G -->|Yes| H[✅ Success]
    G -->|No| I[❌ Fail]
    
    style A fill:#5277C3,color:#fff
    style H fill:#4CAF50,color:#fff
    style I fill:#f44336,color:#fff

Automated Checks:

• ✅ Code formatting (nixfmt/treefmt)
• ✅ Static analysis (statix)
• ✅ CSS syntax validation
• ✅ QML linting
• ✅ Shell script checks
• ✅ Full config evaluation

🎮 Gaming Setup

⚡ CPU Isolation Architecture

[!TIP] Pro Tip: Reserve specific CPU cores for gaming to eliminate system interrupts!

graph TB
    subgraph "🖥️ CPU Core Layout"
        subgraph "🏠 Housekeeping Cores (24 threads)"
            A[Core 4-15]
            B[Core 20-31]
        end
        subgraph "🎮 Gaming Cores ISOLATED (8 threads)"
            C[Core 1-3]
            D[Core 16-19]
        end
    end
    
    G[System Services] --> A
    G --> B
    H[🎮 Games] --> C
    H --> D
    
    style C fill:#4CAF50,color:#fff
    style D fill:#4CAF50,color:#fff
    style H fill:#FF6B35,color:#fff

🚀 Launch Wrappers

# 🎯 Basic CPU pinning
game-run %command%

# 🖥️ With Gamescope (VRR + adaptive sync)
game-run gamescope -f --adaptive-sync -- %command%

# ⚡ Performance preset (low latency)
gamescope-perf %command%

# 🎨 Quality preset (visual fidelity)
gamescope-quality %command%

# 🌈 HDR support
gamescope-hdr %command%

[!NOTE] Steam Launch Options Example (Competitive FPS):

GAME_PIN_CPUSET=1-3,16-19 MANGOHUD=1 game-run gamescope -f --adaptive-sync -- %command%

🎛️ Environment Variables

🌐 Hyprland Configuration

📐 19 Workspaces

💾 Hyprscratch Scratchpads

Quick-access overlays for common applications:

Super+Shift+H hides all scratchpads. Every row mirrors the class match, bind and window rule in files/gui/hypr/hyprland.lua; there is no Discord/Vesktop scratchpad.

🛠️ Custom Packages

30 Custom Packages tailored for productivity and performance:

🎮 Game

Rust launcher wrapper in packages/game/:

• game-run - CPU isolation wrapper with gamescope presets

🎵 Media

• rmpc - Modern MPD client (Rust)
• rustmission - Transmission TUI

💻 Productivity

• two_percent - Optimized fuzzy finder (skim fork)
• duf - Better df with plain style
• comma - Nix ,command wrapper
• pretty_printer - CLI formatting utility

[!NOTE] See packages/ for the complete list.

📚 Documentation

| 💬 Package Annotations | Inline comments | | 🔧 CI Scripts | Development tools |

🤝 Contributing

[!IMPORTANT] This is a personal configuration, but contributions are welcome!

📝 Guidelines

1. 🍴 Fork the repository
2. 🌿 Create a feature branch
3. ✏️ Make your changes
4. ✅ Run just check to verify
5. 📬 Submit a pull request

🎨 Code Style

• ✅ Use nixfmt for formatting
• ✅ Follow existing patterns
• ✅ Test thoroughly before submitting

📜 License

This configuration is available under the MIT License.

🙏 Acknowledgments