homelabby/.planning/ROADMAP.md

Roadmap: HWLab

Overview

HWLab is built in seven phases, each delivering a complete, independently verifiable capability. The foundation establishes the NetBox integration and project scaffold before any feature work. AI photo intake — the core value proposition — is validated as a standalone backend capability before the UI is built around it. USB hardware (arriving 2026-04-13) is characterized and the USB Manager infrastructure is established before cable testing features are layered on top. The Lab Advisor and SearXNG research agent close out the roadmap as enhancement layers that require all primitives to already exist.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Foundation - Go binary scaffold, NetBox integration, custom fields, write-ahead queue (completed 2026-04-10)
• Phase 2: AI Pipeline - oMLX + Gemma 4 setup, three-tier orchestrator, photo intake endpoint, quality gate (completed 2026-04-10)
• Phase 3: Dashboard & Intake UI - React SPA embedded in binary, inventory dashboard, intake flow, item detail view (completed 2026-04-10)
• Phase 4: USB Manager & Label Printing - USB hardware characterization (2026-04-13), goroutine-per-device manager, QR label printing (completed 2026-04-10)
• Phase 5: Cable Test Integration - Treedix USB/DP/HDMI testers, FNIRSI FNB58, cable test workflow UI (completed 2026-04-10)
• Phase 6: Lab Advisor - Claude Opus chat interface, NetBox context assembly, streaming SSE, chat history
• Phase 7: Research Agent & Search - SearXNG Tier 2 research agent, natural language inventory search, quality gate automation

Phase Details

Phase 1: Foundation

Goal: The Go binary connects to NetBox with all custom fields provisioned and a write-ahead queue buffering operations during downtime Depends on: Nothing (first phase) Requirements: INF-01, INF-02, INF-03, NB-01, NB-02, NB-03, NB-04, NB-05, NB-06, NB-07 Success Criteria (what must be TRUE):

1. Running Go binary serves a health endpoint and embeds a stub React SPA
2. All HWLab custom fields (hw_id, catalog_status, photo_urls, etc.) are readable and writable via the NetBox API with round-trip test coverage
3. A new item can be created in NetBox with a sequential HW-XXXXX ID auto-assigned
4. catalog_status transitions from draft through complete are enforced by the backend quality gate
5. A write-ahead queue in DragonFlyDB buffers failed NetBox operations and retries them on reconnect Plans: 5 plans

Plans:

• 01-01-PLAN.md — Go scaffold: chi server, go:embed stub SPA, viper config, health endpoint
• 01-02-PLAN.md — NetBox client: go-netbox v4 wrapper, custom field read/write types, integration tests
• 01-03-PLAN.md — NetBox provisioning: 8 custom fields, location hierarchy, plugin check, provision CLI
• 01-04-PLAN.md — HW-ID allocation, quality gate state machine, AI tag sync to NetBox
• 01-05-PLAN.md — Write-ahead queue: DragonFlyDB WAQ + retry worker goroutine

Phase 2: AI Pipeline

Goal: Users can submit 1-3 photos and receive a structured NetBox-ready record with AI-extracted specs, suggested category/tags, and a quality gate status reflecting confidence Depends on: Phase 1 Requirements: AI-01, AI-02, AI-03, AI-04, AI-05, AI-06, AI-07, AI-08, AI-09 Success Criteria (what must be TRUE):

1. oMLX serves Gemma 4 on Mac Mini M4 with measured memory budget documented
2. POST /api/intake with 1-3 photos returns serial number, model, manufacturer, specs, category, and tags extracted by AI
3. Items with AI confidence below threshold are automatically set to needs_research; high-confidence items advance to indexed
4. Quick add mode skips review for high-confidence items and creates the NetBox record in one step
5. Any AI tier (local oMLX, OpenRouter) can be swapped by changing a config JSON value with no code changes Plans: 4 plans

Plans:

• 02-01-PLAN.md — go-openai dep, CreateDevice on NetBox client, AIClient interface, MockAIClient, TierClient, ai_config.json
• 02-02-PLAN.md — Three-tier orchestrator, WAQ real NetBox op handler, SearXNG ResearchClient stub
• 02-03-PLAN.md — POST /api/intake handler, router wiring, quick add mode, main.go real WAQ handler
• 02-04-PLAN.md — oMLX integration test, memory measurement checkpoint

Phase 3: Dashboard & Intake UI

Goal: Users can browse their full inventory, run intake for new items, and view item detail — all through the React SPA served by the Go binary Depends on: Phase 3 Requirements: UI-01, UI-02, UI-03, UI-04, UI-05, UI-06, PWA-01, PWA-02, PWA-03 Success Criteria (what must be TRUE):

1. Inventory dashboard loads with grid/list toggle, item cards showing photo, HW ID, status, and key specs
2. User can filter inventory by category, tags, catalog status, and location without a page reload
3. User can view full item detail including photos, specs, test data, and audit history
4. Intake flow accepts 1-3 photo uploads, shows AI classification result inline, and allows correction before creating the NetBox record
5. App is installable as a PWA on Android and the camera-based QR scanner resolves items by HW ID Plans: 5 plans

Plans:

• 03-01-PLAN.md — Frontend scaffold: Vite 5 + React 18 + TypeScript + Tailwind + shadcn/ui, ClickHouse design tokens, TanStack Router/Query, Zustand
• 03-02-PLAN.md — Backend inventory endpoints: GET /api/inventory + GET /api/inventory/:id handlers + router wiring
• 03-03-PLAN.md — Dashboard + item detail views: grid/list toggle, filters, ItemCard/ItemRow, item detail with photos and custom fields
• 03-04-PLAN.md — Intake flow UI: DropZone, photo preview, AI result review, confidence meter, wired to POST /api/intake
• 03-05-PLAN.md — PWA setup: manifest.json, service worker, icons, camera QR scanner at /scan

Phase 4: USB Manager & Label Printing

Goal: USB peripherals are managed by a goroutine-per-device subsystem and any cataloged item can have a QR-coded label printed by the PRT Qutie without operator intervention after intake Depends on: Phase 3 Requirements: USB-01, USB-02, USB-03, USB-04, LBL-01, LBL-02, LBL-03, LBL-04, LBL-05 Success Criteria (what must be TRUE):

1. USB Manager discovers the PRT Qutie by VID/PID and reconnects automatically after unplug/replug without path reconfiguration
2. USB device connect/disconnect events appear in the frontend in real time via SSE
3. A QR label with HW ID, item name, key spec line, and QR code is printed for any item from the dashboard quick actions
4. Cable-specific label template correctly shows USB version, speed, wattage, and test date
5. Label printing completes as the final step of the AI intake workflow without leaving the intake screen Plans: 5 plans

Plans:

• 04-01-PLAN.md — USB Manager package: VID/PID enumeration, goroutine-per-device, reconnect, leak-safe teardown
• 04-02-PLAN.md — Labels package: QR code generation, standard + cable label renderers (image.Image output)
• 04-03-PLAN.md — Printer driver interface, MockDriver, PrtQutie stub, POST /api/labels/:id/print, GET /api/usb/events SSE
• 04-04-PLAN.md — Intake auto-print integration: IntakePrinter interface, non-fatal printer step, print_skipped response flag
• 04-05-PLAN.md — Frontend: useUSBEvents hook, USBStatusBar component, Print Label button on dashboard

Phase 5: Cable Test Integration

Goal: Any cable can be tested, its results written to NetBox, and a label printed in a rapid test-verify-print workflow without leaving the Cable Test Station view Depends on: Phase 4 Requirements: CBL-01, CBL-02, CBL-03, CBL-04, CBL-05, CBL-06, CBL-07 Success Criteria (what must be TRUE):

1. Plugging any Treedix tester into USB triggers auto-detection by VID/PID and activates the correct test flow
2. USB, DisplayPort, and HDMI cable test results (continuity, version, eMarker, PD, resistance) are displayed in the Cable Test Station UI and written to the NetBox cable record as structured JSON
3. FNIRSI FNB58 live voltage/current/PD protocol data streams to the UI and is persisted to the cable record
4. A cable can go from test to label printed in under 30 seconds using the rapid workflow Plans: 3 plans

Plans:

• 05-01-PLAN.md — Tester driver package: TesterDriver interface, TestResult/LiveReading types, mock USB/DP/HDMI/FNB58 drivers, VID:PID registry entries
• 05-02-PLAN.md — Backend: CreateCable on NetBox client, TestHandler (POST /api/test/cable, GET /api/test/events SSE, GET /api/test/recent), router + main.go wiring
• 05-03-PLAN.md — Frontend: Cable Test Station page at /test (three-panel layout, Print & Next workflow, SSE live readout, mobile-responsive)

Phase 6: Lab Advisor

Goal: Users can ask strategic homelab questions and receive streaming answers from Claude Opus with full inventory context, with conversation history persisted across sessions Depends on: Phase 5 Requirements: ADV-01, ADV-02, ADV-03, ADV-04, ADV-05 Success Criteria (what must be TRUE):

1. Chat interface sends a question and receives a streaming response from Claude Opus via OpenRouter with no page reload
2. Each conversation automatically includes a pre-loaded NetBox inventory context summary
3. Conversation history persists across browser sessions and is viewable in the chat UI
4. Model can be switched from Opus to any OpenRouter-compatible model via the dropdown without restarting the server Plans: TBD UI hint: yes

Phase 7: Research Agent & Search

Goal: Items flagged needs_research are automatically enriched by a SearXNG research agent, and any inventory question can be answered via natural language search Depends on: Phase 6 Requirements: AI-04 Success Criteria (what must be TRUE):

1. An item at needs_research status is automatically enriched with product specs, datasheet links, and pricing by the SearXNG Tier 2 agent and advances to researched
2. Natural language search ("show me all free 10GbE NICs") returns filtered inventory results drawn from NetBox
3. SearXNG queries are sanitized before dispatch — no raw AI output reaches the search engine

Note: AI-04 is the sole unmapped requirement from Phase 2 that belongs here — it requires the full orchestrator, SearXNG client, and NetBox inventory all in place. The other Phase 2 requirements cover Tier 1 intake; this requirement covers the Tier 2 research loop. Plans: TBD

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7

Phase	Plans Complete	Status	Completed
1. Foundation	5/5	Complete	2026-04-10
2. AI Pipeline	4/4	Complete	2026-04-10
3. Dashboard & Intake UI	5/5	Complete	2026-04-10
4. USB Manager & Label Printing	5/5	Complete	2026-04-10
5. Cable Test Integration	3/3	Complete	2026-04-10
6. Lab Advisor	0/TBD	Not started	-
7. Research Agent & Search	0/TBD	Not started	-