7.6 KiB
7.6 KiB
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