tfm_ainventory/PLAN.md

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

• Phase 1: Backend Foundation (FastAPI, SQLite, Models).
• Phase 2: Modular AI Integration (Gemini & Claude support, v2 SDK).
• Phase 3: AI Onboarding UI (Validation Mask, Camera/Upload integration).
• Phase 4: Offline Synchronization (Deduplicated Dexie -> SQL sync logic).
• 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.