Inventory PWA System Architecture & Implementation Plan

This document defines the technical architecture and rules for the InventoryAI System (2026 Edition).

1. Core Architecture

See the detailed dev_docs/TECH_STACK.md for official framework, database, and library versions. Summary: FastAPI / Python 3.12+ (Backend) & Next.js 15+ PWA (Frontend). Sync via Dexie.js (client side) and SQL sync logic (v1.2.4).

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.

2.6 KiB Raw Blame History