🕹️ KV Home (Procedural Tetris Homelab Hub)

The procedural Tetris-tiling personal dashboard, service hub, and homelab app launcher.
Every service card is an interlocking tetromino that dynamically drops and locks into place.
Built with React 19, Vite 7, and a hardened zero-dependency Node.js backend with native TOTP 2FA.

Quick Start • Why KV Home? • Comparison • Tetris Engine • Security & 2FA • Star History

---

⚡ Why KV Home?

Most homelab dashboards (like Homepage, Dashy, or Flame) use rigid grid rows and flat cards that feel like generic admin templates.

KV Home transforms your service launcher into a tactile, dynamic experience:

• 🧩 Procedural Tetris Tiling Engine: A backtracking solver arranges cards into interlocking tetrominoes (I, J, L, O, S, T, Z) that animate and fall smoothly on page load.
• 🔐 Native RFC 6238 TOTP 2FA: Built directly with standard cryptographic libraries—protect your management portal without needing external authenticators like Authelia or Authentik.
• 🎬 HTTP 206 Partial Content Video Streaming: Embed background video loops and resume media with zero buffering across Safari, Chrome, and mobile devices.
• 🚀 Zero-Dependency Production Backend: The backend is written with standard Node.js libraries (node:http, node:crypto, node:fs). Zero third-party npm packages required at runtime!
• 🛠️ In-Place Live Admin Mode: Press Ctrl + Shift + A to add, reorder, adjust colors, and edit links with immediate multi-device synchronization.

---

📊 Competitive Comparison

Feature	🕹️ KV Home	🏠 Homepage	⚡ Dashy	🔥 Flame
Visual Architecture	Procedural Tetris Tetrominoes	Static Grid	Column/Row Widgets	Flat Cards
Built-in TOTP 2FA	✅ Native RFC 6238 (Zero-Dep)	❌ Needs Reverse Proxy	⚠️ Basic Auth	⚠️ Password only
Runtime Dependencies	⚡ Zero (Node.js Standard Libs)	Many npm packages	Heavy Node stack	Ruby / Docker
Live In-Place Editing	✅ Hotkey Ctrl+Shift+A	❌ Edit YAML files	✅ GUI Editor	✅ GUI Editor
Video Background Streaming	✅ HTTP Range 206 Support	❌ Static images	❌ Static images	❌ Static
Synology NAS Ready	✅ 1-Container Deployment	✅ Docker	✅ Docker	✅ Docker

---

📸 Interface Preview

┌────────────────────────────────────────────────────────────────────────────────────────┐
│ [🕹️ KV Home]                             [🎲 Re-roll] [🌙 Dark] [⚙️ Admin (Ctrl+Shift+A)] │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│   ┌──────────────┐┌──────────────┐┌────────────────────────────┐┌──────────────┐      │
│   │ 📁 KV Files  ││ 🔮 SysVis.AI ││ 📥 KV-DL Downloader        ││ 🌐 Blog      │      │
│   │ Rust Manager ││ System AI    ││ Zero-Disk YouTube Engine   ││ Tech Notes   │      │
│   └──────┬───────┘└──────┬───────┘└─────────────┬──────────────┘└──────┬───────┘      │
│          │ ┌─────────────┴┐ ┌───────────────────┴──┐ ┌─────────────────┴────┐          │
│          │ │ 📺 Jellyfin  │ │ 🐳 Portainer Stack   │ │ 📊 Grafana Metrics   │          │
│          │ │ 4K Media     │ │ Docker Services      │ │ Cluster Monitor      │          │
│          └─┴──────────────┘ └──────────────────────┘ └──────────────────────┘          │
│                                                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘

---

🎯 Procedural Tetris Engine

KV Home computes layout geometries using an in-browser constraint solver:

1. Dimension Analysis: Calculates optimal board width from the client's screen ratio.
2. Backtracking Tetromino Placement: Fits L-shapes, T-shapes, squares, and line pieces with zero gaps.
3. Seamless SVG Clipping: Blocks render as continuous geometric shapes using SVG clipPath and CSS calc() to prevent awkward seam lines while keeping consistent gutters.
4. Interactive Re-Roll: Click the 🎲 Shuffle button to re-roll tetromino configuration seeds instantly.

---

🚀 Quick Start (30 Seconds)

Option A: Run Prebuilt Docker Container

Run KV Home immediately on port 3000:

docker run -d \
  --name kv-home \
  -p 3000:3000 \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  vndangkhoa/kv-home:latest

Open http://localhost:3000 in your browser.

---

Option B: Docker Compose (Recommended)

services:
  kv-home:
    image: vndangkhoa/kv-home:latest
    container_name: kv-home
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      # Persistent link data and 2FA credentials
      - ./data:/app/data
      # Uploaded media and background videos
      - ./uploads:/app/uploads
      # Real-time Docker container status
      - /var/run/docker.sock:/var/run/docker.sock:ro

Start the service:

docker compose up -d

---

🔐 Security & TOTP 2FA

KV Home is hardened for public exposure on personal domains:

• Two-Factor Authentication: RFC 6238 TOTP with QR Code scanner compatible with Google Authenticator, Apple Passwords, 1Password, and Authy.
• Salted scrypt Passwords: Hashes credentials with unique 16-byte random salts.
• Side-Channel Defense: Uses crypto.timingSafeEqual to defeat timing attacks.
• Brute-Force Lockout: Automatically locks out IP addresses for 15 minutes after 5 consecutive failed attempts.
• Hardened HTTP Headers: Strict CSP, X-Frame-Options: DENY, X-Content-Type-Options: nosniff.

---

⌨️ Shortcuts & Admin Navigation

Key	Scope	Action
Ctrl + Shift + A	Global	Open / Close Admin Management Modal
Esc	Modal	Close active configuration dialog
Space	Canvas	Re-roll Tetris piece layout configuration

---

🌟 Support & Community

If KV Home makes your homelab feel more playful and functional:

• Give the repository a Star ⭐ on GitHub!
• Share your dashboard on Reddit r/selfhosted or r/homelab
• Contribute layout algorithms or features via GitHub Issues

---

📄 License

Distributed under the MIT License. See LICENSE for complete details.

Developed with ❤️ by Khoa Vo (@vndangkhoa).