56 lines
3.0 KiB
Markdown
56 lines
3.0 KiB
Markdown
# Inventory PWA System Architecture & Implementation Plan
|
|
|
|
This document defines the technical architecture and rules for the InventoryAI System (2026 Edition).
|
|
|
|
## 1. Core Architecture
|
|
|
|
### 1.1 Backend (Python 3.14+)
|
|
- **Framework:** FastAPI
|
|
- **Database:** SQLite (SQLAlchemy) - chosen for local performance and simplicity.
|
|
- **Organization:** Modular design with separate routers for Items and Operations.
|
|
|
|
### 1.2 Frontend (Next.js 15+ PWA)
|
|
- **State Management:** React Hooks + Dexie.js (IndexedDB wrapper).
|
|
- **Offline Engine:**
|
|
- Service Workers for asset caching.
|
|
- IndexedDB for local data persistence.
|
|
- Sync mechanism: Local changes are buffered and pushed to backend when online.
|
|
- **Scanner:** `html5-qrcode` for standard barcode/QR detection (Local-only).
|
|
|
|
## 2. AI Intelligence Strategy (Critical)
|
|
|
|
### 2.1 AI Usage Policy
|
|
- **New Item Onboarding:** AI-OCR is permitted. It analyzes complex label photos (SFP, hardware specs) and maps them to JSON fields.
|
|
- **Routine Operations (Check-in/Out/Audit):** **AI IS STRICTLY FORBIDDEN.**
|
|
- Use local barcode/QR scanning only.
|
|
- If a label is not recognized locally, the user is prompted to start the "AI Onboarding Assistant".
|
|
- Goal: $0 cost for 99% of daily operations.
|
|
|
|
### 2.2 Modular AI Providers Architecture
|
|
Located in `backend/ai/`, the system supports multiple providers through a managed orchestrator:
|
|
- **Provider Modules:** `gemini.py`, `claude.py`, etc.
|
|
- **SDK Update (v2):** Switched to `google-genai` (v2) for improved stability and response parsing.
|
|
- **Model Hardcoding Power:** Switched from dynamic discovery to fixed high-speed models (`gemini-2.0-flash`) for sub-second responses on cellular networks.
|
|
|
|
### 2.3 Hybrid Sync & Deduplication (New)
|
|
To ensure zero data loss during unstable mobile sessions:
|
|
- **UUID Labeling:** Every sync operation generated on a mobile device is tagged with a client-side UUID.
|
|
- **Idempotent Backend:** The `bulk_sync` endpoint checks UUIDs against `AuditLog` before applying increments, preventing double-counts.
|
|
|
|
## 3. Data Integrity & Audit
|
|
- **Immutable Audit Log:** Every change (Add, Remove, Edit) is logged with a timestamp, action, and previous/new state.
|
|
- **Validation Mask:** AI-extracted data is NEVER saved directly. It is presented to a human user in a validation UI for final confirmation.
|
|
|
|
## 4. Implementation Status
|
|
|
|
- [x] **Phase 1: Backend Foundation** (FastAPI, SQLite, Models).
|
|
- [x] **Phase 2: Modular AI Integration** (Gemini & Claude support, v2 SDK).
|
|
- [x] **Phase 3: AI Onboarding UI** (Validation Mask, Camera/Upload integration).
|
|
- [x] **Phase 4: Offline Synchronization** (Deduplicated Dexie -> SQL sync logic).
|
|
- [x] **Phase 5: Inventory Trash Management** (Waste/Discard/Damage workflow).
|
|
- [ ] **Phase 6: Audit Log Dashboard UI** (Visual historical interventions).
|
|
|
|
## 5. Security & Infrastructure
|
|
- **Unified SSL Proxy:** Integrated `local-ssl-proxy` for HTTPS access (Camera/Mic) on port 3003.
|
|
- **VENV Isolation:** Automated `.venv` management in `start_server.sh`.
|