Infrastructure: Implement master/dev/vX branching, save git path, and fix username casing

PLAN.md

@@ -1,31 +1,55 @@
-# Inventory PWA System Implementation Plan
+# Inventory PWA System Architecture & Implementation Plan
 
-This document outlines the technical architecture for the unified Inventory System (FastAPI + PWA).
+This document defines the technical architecture and rules for the InventoryAI System (2026 Edition).
 
-## Proposed Architecture
+## 1. Core Architecture
 
-### 1. Backend Server (Linux / Docker)
-- **Framework:** Python + FastAPI
-- **Database:** SQLite (SQLAlchemy ORM)
-- **Key Modules:**
-  - `Items / Interventions`: Standard CRUD logic.
-  - `Audit`: Every payload that mutates data writes an immutable log row.
-  - `AI-OCR`: Endpoint integrating Google Gemini Vision API (via Google AI Studio key) for complex label extraction onboarding.
+### 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.
 
-### 2. Unified Web Application (PWA)
-- **Framework:** React + Next.js (or equivalent).
-- **Offline Engine:** Service Workers, IndexedDB local storage map.
-- **Desktop Mode:** Full width dashboard, management, and settings.
-- **Mobile Mode (Browser / Add to Homescreen):** Dedicated full-screen scanner using `html5-qrcode`.
+### 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).
 
-### 3. AI Cost Strategy
-- **Routine Scans (Check-ins/Outs):** Client-side HTML5 barcode scanner. **Cost: $0.**
-- **Label Scanning (New Item):** Proxies a request to the Gemini API to parse the SFP label into JSON template fields.
+## 2. AI Intelligence Strategy (Critical)
 
-## Implementation Phases
+### 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.
 
-- **Phase 1: Database & Backend Foundation** - SQLite schemas, User management, and Python API structures.
-- **Phase 2: Core Inventory API** - Endpoints to Add/Remove items, offline sync-merge logic, Audit triggers.
-- **Phase 3: The PWA Frontend** - PWA manifest, offline capabilities, UI scaffolding for Desktop/Mobile.
-- **Phase 4: Client-Side Scanning** - Integration of local JS barcode reading for routine stock scanning.
-- **Phase 5: Gemini AI Vision Integration** - Server-side Gemini API integration and the text-mapping frontend view.
+### 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`.