# 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*