# 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`.