mikkel/homelabby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
homelabby/.planning/PROJECT.md

4.8 KiB
Raw Blame History

HWLab

What This Is

HWLab is a self-hosted, AI-powered hardware inventory management system for homelab environments. It combines local multimodal AI (Gemma 4 via oMLX) for photo-based intake and categorization, NetBox as the authoritative inventory database, and automated label printing with integrated cable testing workflows. Built with Go + React, running entirely on a Mac Mini M4.

Core Value

Any physical item can be cataloged by uploading a photo — AI extracts data, creates a NetBox record, and prints a QR-coded label — with zero manual data entry for 80-90% of items.

Requirements

Validated

(None yet — ship to validate)

Active

  • AI-powered hardware intake via photo upload (Gemma 4 local inference)
  • Three-tier AI pipeline: local indexer, research agent, lab advisor
  • NetBox integration as sole source of truth for all inventory data
  • Automated QR-coded label printing via PRT Qutie thermal printer
  • Cable testing workflows with Treedix USB/DP/HDMI testers
  • Live USB power testing with FNIRSI FNB58
  • Inventory dashboard with AI-powered natural language search
  • Lab Advisor chat interface backed by Claude Opus
  • SearXNG integration for automated product research
  • Provider-agnostic AI routing via OpenAI-compatible endpoints
  • Universal HW-XXXXX ID scheme with QR-encoded item URLs
  • Catalog quality gate (draft/indexed/needs_research/researched/complete)

Out of Scope

  • Barcode scanner integration — future consideration
  • Mobile companion app / PWA — web-first for v1
  • SNMP/network discovery — manual and AI intake only for v1
  • Bulk import mode ("box of 50 cables") — defer to post-MVP
  • Automated NetBox topology map updates — future consideration
  • Real-time chat/collaboration — solo operator tool

Context

  • Target machine: Mac Mini M4 (16GB unified memory) running macOS
  • NetBox: Running in Proxmox LXC 130 (10.5.0.130:8000), API token: homelab-netbox-api-token-2024, DNS: netbox.lab.georgsen.dk, external: netbox.georgsen.dk — needs netbox-inventory plugin and custom fields
  • oMLX: Not yet installed — needs setup with Gemma 4 model on Mac Mini
  • SearXNG: Running in Proxmox LXC 129 (10.5.0.129:8080), JSON API: http://10.5.0.129:8080/search?q=query&format=json, DNS: searxng.lab.georgsen.dk, external: search.georgsen.dk — no auth needed
  • Community Postgres: Available in homelab infrastructure
  • DragonFlyDB: Available in homelab infrastructure — candidate for write-ahead queue / caching
  • USB peripherals arriving: Monday 2026-04-13 (PRT Qutie printer, Treedix testers, FNIRSI FNB58)
  • Git remote: git.georgsen.dk
  • Design system: ClickHouse-inspired (pure black + neon volt) — not Tokyo Night as originally brainstormed
  • Solo operator: Mikkel's homelab, no multi-user requirements

Constraints

  • Hardware: Mac Mini M4 with 16GB — Gemma 4 model must fit in memory (E4B confirmed, 26B A4B needs testing with TurboQuant)
  • No cloud dependency: Standard operations must work fully local — OpenRouter only for Tier 2/3 AI
  • NetBox is source of truth: HWLab stores no inventory data locally (only advisor chat history + config in SQLite)
  • USB protocols: Printer and tester protocols need reverse-engineering once hardware arrives
  • Tech stack: Go backend, React TypeScript frontend, Tailwind CSS

Key Decisions

Decision Rationale Outcome
NetBox as sole data store Leverage existing ecosystem, avoid data duplication -- Pending
Universal HW-XXXXX IDs Category-agnostic — AI handles categorization, not the ID -- Pending
Three-tier AI model Local-first for cost/speed, escalate only when needed -- Pending
ClickHouse design system Global default DESIGN.md, high-contrast dark theme -- Pending
OpenRouter for remote AI Provider-agnostic, any model via config swap -- Pending
Go + React stack Go for USB/serial control and backend; React for dynamic SPA -- Pending
oMLX for local inference Apple Silicon optimized, MLX backend for Gemma 4 -- Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

  1. Requirements invalidated? -> Move to Out of Scope with reason
  2. Requirements validated? -> Move to Validated with phase reference
  3. New requirements emerged? -> Add to Active
  4. Decisions to log? -> Add to Key Decisions
  5. "What This Is" still accurate? -> Update if drifted

After each milestone (via /gsd-complete-milestone):

  1. Full review of all sections
  2. Core Value check — still the right priority?
  3. Audit Out of Scope — reasons still valid?
  4. Update Context with current state

Last updated: 2026-04-09 after initialization