# Requirements: HWLab

**Defined:** 2026-04-09
**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.

## v1 Requirements

### NetBox Integration

- [ ] **NB-01**: System connects to NetBox REST API and performs CRUD on devices, modules, and cables
- [ ] **NB-02**: Custom fields provisioned in NetBox (hw_id, catalog_status, product_url, firmware_version, test_date, test_data, ai_notes, photo_urls)
- [ ] **NB-03**: netbox-inventory plugin installed and configured for asset lifecycle tracking
- [ ] **NB-04**: Location hierarchy created in NetBox (Site → Location → Rack per PRD section 7.6)
- [ ] **NB-05**: Write-ahead queue buffers NetBox operations during network issues (DragonFlyDB available in homelab)
- [ ] **NB-06**: Catalog quality gate enforced via catalog_status field (draft → indexed → needs_research → researched → complete)
- [ ] **NB-07**: AI-generated tags synced to NetBox tag system

### AI Pipeline

- [ ] **AI-01**: oMLX installed on Mac Mini M4 with Gemma 4 model serving OpenAI-compatible API
- [ ] **AI-02**: User can upload 1-3 photos and AI extracts serial number, model, manufacturer, specs via multimodal vision
- [ ] **AI-03**: AI suggests category, tags, and location for each item
- [ ] **AI-04**: AI calls SearXNG via function calling to research product specs and datasheets
- [ ] **AI-05**: Orchestrator reviews Tier 1 output for completeness and flags gaps as needs_research
- [ ] **AI-06**: Tier 2 research agent (OpenRouter) automatically enriches items flagged needs_research
- [ ] **AI-07**: Quick add mode skips review screen for items with high AI confidence
- [ ] **AI-08**: All AI tiers accessed via single OpenAI-compatible client with configurable base URLs
- [ ] **AI-09**: Provider routing configured via JSON file — swap any tier without code changes

### Label Printing

- [ ] **LBL-01**: QR code generated for each item encoding URL (http://mac-mini.mg:8080/hw/XXXXX)
- [ ] **LBL-02**: Label contains QR code, HW ID, item name, and key spec line
- [ ] **LBL-03**: Cable-specific label template shows USB version, speed, wattage, test date
- [ ] **LBL-04**: Labels printed via PRT Qutie thermal printer over USB serial
- [ ] **LBL-05**: Label printing integrated as final step of AI intake workflow

### Cable Testing

- [ ] **CBL-01**: USB cable test data read from Treedix USB tester via USB serial (pin continuity, USB version, eMarker, PD, resistance)
- [ ] **CBL-02**: DisplayPort cable test data read from Treedix DP tester
- [ ] **CBL-03**: HDMI cable test data read from Treedix HDMI tester
- [ ] **CBL-04**: FNIRSI FNB58 live voltage/current/PD protocol data read via USB or Bluetooth
- [ ] **CBL-05**: Cable record auto-created in NetBox with structured test_data JSON
- [ ] **CBL-06**: Rapid test → verify → print → next workflow in Cable Test Station view
- [ ] **CBL-07**: Auto-detect which tester is connected via USB VID/PID enumeration

### Dashboard & Search

- [ ] **UI-01**: Inventory dashboard with grid/list toggle showing item cards (photo, name, HW ID, status, key specs)
- [ ] **UI-02**: Filter inventory by category, tags, catalog status, and location
- [ ] **UI-03**: AI-powered natural language search ("show me all free 10GbE NICs")
- [ ] **UI-04**: Item detail view with photos, full specs, test data, and audit history
- [ ] **UI-05**: Quick actions from dashboard: print label, view in NetBox, edit
- [ ] **UI-06**: ClickHouse-inspired design system (pure black #000000, neon volt #faff69)

### Lab Advisor

- [ ] **ADV-01**: Chat interface for strategic homelab questions backed by Claude Opus via OpenRouter
- [ ] **ADV-02**: Inventory context from NetBox pre-loaded into each conversation
- [ ] **ADV-03**: Conversation history persisted locally in SQLite
- [ ] **ADV-04**: Model selection dropdown (Opus default, configurable to other OpenRouter models)
- [ ] **ADV-05**: Response streaming via SSE to chat UI

### USB Device Management

- [ ] **USB-01**: USB device manager discovers peripherals by VID/PID, not path
- [ ] **USB-02**: Goroutine-per-device model with channel-based command/event pattern
- [ ] **USB-03**: Graceful reconnect handling when devices are unplugged and replugged
- [ ] **USB-04**: Device events pushed to frontend via SSE

### Mobile / PWA

- [ ] **PWA-01**: Progressive Web App installable on Android for QR code scanning
- [ ] **PWA-02**: Item detail view accessible and usable on mobile screen sizes
- [ ] **PWA-03**: Camera-based QR scanner to look up items by HW ID

### Infrastructure

- [ ] **INF-01**: Go backend serves React SPA via go:embed (single binary)
- [ ] **INF-02**: Configuration via JSON file + environment variables
- [ ] **INF-03**: HW-XXXXX sequential ID auto-assigned at intake, stored as NetBox asset_tag

## v2 Requirements

### Bulk Operations

- **BULK-01**: Bulk import mode for high-volume scenarios (box of 50 cables)
- **BULK-02**: Barcode scanner HID support for existing barcodes

### Network Discovery

- **NET-01**: SNMP/network discovery to auto-populate device inventory

### Integrations

- **INT-01**: Automated NetBox topology map updates from cable test endpoints
- **INT-02**: Integration with homelab agent (LXC 102) for infrastructure-aware operations

## Out of Scope

| Feature | Reason |
|---------|--------|
| Multi-user / RBAC | Solo operator tool — NetBox has RBAC if truly needed |
| Real-time collaboration | Single-operator homelab; advisor chat is async single-session |
| CSV bulk import bypassing AI | Creates data quality debt; use AI intake as canonical path |
| Local LLM fine-tuning UI | Out of scope for inventory tool; prompt engineering + SearXNG sufficient |
| Predictive failure / warranty alerts | Alert infrastructure disproportionate to homelab context |
| Network topology auto-update | Topology inference from cable tests is ambiguous; manual updates |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| NB-01 | Phase 1 | Pending |
| NB-02 | Phase 1 | Pending |
| NB-03 | Phase 1 | Pending |
| NB-04 | Phase 1 | Pending |
| NB-05 | Phase 1 | Pending |
| NB-06 | Phase 1 | Pending |
| NB-07 | Phase 1 | Pending |
| AI-01 | Phase 2 | Pending |
| AI-02 | Phase 2 | Pending |
| AI-03 | Phase 2 | Pending |
| AI-04 | Phase 7 | Pending |
| AI-05 | Phase 2 | Pending |
| AI-06 | Phase 2 | Pending |
| AI-07 | Phase 2 | Pending |
| AI-08 | Phase 2 | Pending |
| AI-09 | Phase 2 | Pending |
| LBL-01 | Phase 4 | Pending |
| LBL-02 | Phase 4 | Pending |
| LBL-03 | Phase 4 | Pending |
| LBL-04 | Phase 4 | Pending |
| LBL-05 | Phase 4 | Pending |
| CBL-01 | Phase 5 | Pending |
| CBL-02 | Phase 5 | Pending |
| CBL-03 | Phase 5 | Pending |
| CBL-04 | Phase 5 | Pending |
| CBL-05 | Phase 5 | Pending |
| CBL-06 | Phase 5 | Pending |
| CBL-07 | Phase 5 | Pending |
| UI-01 | Phase 3 | Pending |
| UI-02 | Phase 3 | Pending |
| UI-03 | Phase 7 | Pending |
| UI-04 | Phase 3 | Pending |
| UI-05 | Phase 3 | Pending |
| UI-06 | Phase 3 | Pending |
| ADV-01 | Phase 6 | Pending |
| ADV-02 | Phase 6 | Pending |
| ADV-03 | Phase 6 | Pending |
| ADV-04 | Phase 6 | Pending |
| ADV-05 | Phase 6 | Pending |
| USB-01 | Phase 4 | Pending |
| USB-02 | Phase 4 | Pending |
| USB-03 | Phase 4 | Pending |
| USB-04 | Phase 4 | Pending |
| PWA-01 | Phase 3 | Pending |
| PWA-02 | Phase 3 | Pending |
| PWA-03 | Phase 3 | Pending |
| INF-01 | Phase 1 | Pending |
| INF-02 | Phase 1 | Pending |
| INF-03 | Phase 1 | Pending |

**Coverage:**
- v1 requirements: 46 total
- Mapped to phases: 46
- Unmapped: 0

---
*Requirements defined: 2026-04-09*
*Last updated: 2026-04-09 after roadmap creation — all 46 requirements mapped*