From ff93f4f7447539c63e2960a573b99148801fe3ee Mon Sep 17 00:00:00 2001 From: Mikkel Georgsen Date: Thu, 9 Apr 2026 22:35:48 +0000 Subject: [PATCH] docs: initialize project --- .planning/PROJECT.md | 90 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 .planning/PROJECT.md diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md new file mode 100644 index 0000000..0949697 --- /dev/null +++ b/.planning/PROJECT.md @@ -0,0 +1,90 @@ +# 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**: Partially deployed in Proxmox LXC at netbox.georgsen.dk — needs netbox-inventory plugin and custom fields +- **oMLX**: Not yet installed — needs setup with Gemma 4 model on Mac Mini +- **SearXNG**: Already running in existing infrastructure +- **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*