docs: initialize project
This commit is contained in:
commit
ff93f4f744
1 changed files with 90 additions and 0 deletions
90
.planning/PROJECT.md
Normal file
90
.planning/PROJECT.md
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
# 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**: Partially deployed in Proxmox LXC at netbox.georgsen.dk — needs netbox-inventory plugin and custom fields
|
||||
- **oMLX**: Not yet installed — needs setup with Gemma 4 model on Mac Mini
|
||||
- **SearXNG**: Already running in existing infrastructure
|
||||
- **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*
|
||||
Loading…
Add table
Reference in a new issue