Designing a Procedural Tetris-Tiled Homelab Dashboard with a Zero-Dependency Backend

If you browse r/homelab or self-hosted communities, you'll see dozens of dashboards: Homepage, Dashy, Flame, Homer, and others.

While they are capable tools, they often suffer from two common design patterns:

1. Visual Monotony: Almost every dashboard is either a flat 12-column CSS grid or a list of bootstrap cards. After a while, they all look the same.
2. Dependency Bloat: Running a dashboard often requires dozens of npm dependencies or external authentication proxies (like Authelia or Authentik) just to protect access.

I wanted a personal launchpad that was playful, visually striking, yet rock-solid and secure.

That inspired KV Home: a procedural Tetris-tiling personal dashboard and homelab hub.

---

🕹️ The Procedural Tetris Layout Engine

Instead of placing cards into rigid rectangular slots, KV Home uses an in-browser backtracking constraint solver to pack your service links into interlocking tetromino shapes (I, J, L, O, S, T, Z):

┌────────────────────────────────────────────────────────────────────────────────────────┐
│ [🕹️ 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      │          │
│          └─┴──────────────┘ └──────────────────────┘ └──────────────────────┘          │
└────────────────────────────────────────────────────────────────────────────────────────┘

How the Layout Solver Works:

1. Aspect Ratio Analysis: The engine evaluates the client's screen width and determines the optimal grid matrix size.
2. Tetromino Fitting: A recursive backtracking algorithm tiles the matrix with zero empty holes, assigning random tetromino geometries to each of your services.
3. SVG clipPath Rendering: Using dynamic SVG clipping and CSS calc(), individual blocks form continuous geometric shapes with consistent gutters and zero visual seams.
4. Interactive Re-Roll: Click the 🎲 Re-roll button or press space, and the engine re-seeds the solver, animating new falling tetrominoes into position!

---

🔒 Hardened Zero-Dependency Node.js Backend

One of my core design goals was eliminating runtime third-party dependency vulnerabilities.

The KV Home backend uses only standard Node.js built-in modules:

• node:http: Fast native HTTP/1.1 request handling.
• node:crypto: High-speed cryptographic operations.
• node:fs / node:path: Local configuration persistence and asset serving.

Zero third-party npm packages are loaded in production. This dramatically minimizes security attack surfaces and memory overhead.

Built-in RFC 6238 TOTP 2FA

Securing your homelab dashboard usually involves configuring a complex reverse proxy with OAuth/OIDC.

KV Home includes a native implementation of RFC 6238 Time-Based One-Time Passwords (TOTP) written with node:crypto. You can scan a QR code with Google Authenticator, 1Password, or Bitwarden directly from the setup wizard, providing robust 2-factor protection out of the box with zero external dependencies.

---

🛠️ Live In-Place Admin Mode (Ctrl + Shift + A)

No need to open terminal sessions, edit YAML files, and reload Docker containers every time you add a new service.

Pressing Ctrl + Shift + A activates In-Place Admin Mode:

• Add new service cards and category tags directly on the dashboard.
• Pick icons, custom accents, and health-check endpoints.
• Rearrange priorities with real-time multi-device sync.

---

🚀 Quick Start with Docker

Deploy KV Home in seconds:

docker run -d \
  --name kv-home \
  -p 3000:3000 \
  -v ./kv-home-data:/app/data \
  vndangkhoa/kv-home:latest

Open http://localhost:3000 to experience your new homelab hub.

---

🔗 Check it Out on GitHub

KV Home is completely open-source under the MIT license:

⭐ GitHub Repository: https://github.com/vndangkhoa/kv-home

🐳 Docker Hub: vndangkhoa/kv-home

Give your homelab a fresh, tactile look!