92 lines
4.8 KiB
Markdown
92 lines
4.8 KiB
Markdown
# 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*
|