TFM aInventory - Project Architecture & Requirements

This document is the Single Source of Truth for the project's technical architecture, business requirements, and core logic.

1. Application Overview

A unified system to maintain an inventory of "items" and their quantities, inclusive of a web administration interface, offline field operations, audit logging, and AI-powered label extraction functionalities.

2. Technical Stack

2.1 Backend (API & Data)

Language: Python 3.12+ (Optimized for performance and type safety)
Framework: FastAPI (Async ASGI)
Database: SQLite (SQLAlchemy) - Local file-based persistence
Validation: Pydantic v2
Auth: Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching
AI Engine: Google GenAI SDK (Gemini 2.0 Flash) - Location: backend/ai/

2.2 Frontend (Web & PWA)

Architecture: Next.js 15+ (App Router)
Styling: Tailwind CSS (Readability-first config)
Icons: Lucide Icons (React components)
Offline persistence: Dexie.js (IndexedDB wrapper)
Scanner: html5-qrcode (Client-side, offline-only)
Sync: Axios with bulk-sync idempotency (UUID-based)

2.3 Operations & Tooling

PWA Deployment: next-pwa (Service Workers + Manifest.json)
HTTPS Proxy: local-ssl-proxy (Required for mobile camera access, Port 3003)
Servers: Frontend (npm run dev on 3000), Backend (./start_server.sh on 8000)

3. Data Models & Entities

Item: Name, Category Group (Structured), Item Type (Specific), Quantity, Barcode, Part Number.
Category: Predefined groups for organizational structure.
Intervention: Linked to a required items list.
Audit Log: Immutable ledger detailing CRUD operations and stock fluctuations.

4. Scanning & Optimization Strategy (Crucial)

4.1 AI Usage Policy

Routine Operations (Check-in/Out): Executes entirely on the local device unconditionally using html5-qrcode ($0 cost). No AI is allowed here.
New Item Onboarding (AI Label OCR): Uses cloud AI (gemini-2.0-flash). The user takes a photo, AI extracts data based on strict templates.
Validation Mask: AI-extracted data is NEVER saved directly. It is presented in a validation UI for human confirmation.

4.2 Scanner Technical Specs (FROZEN)

Hardware Access: Direct MediaStreamTrack access. Zoom cycle: 1x -> 2x -> Max/2 -> Max.
Image Pre-processing: Rescaling (1200px), 60% Center Crop, Grayscale/Contrast filters, JPEG (0.85 quality).
OCR Matching Engine (page.tsx):
- Noise Filtering: Ignores < 3 chars, decimals, and dates.
- Scoring: Exact S/N (+500), Exact P/N (+200), Token match (+50), Category match (+20).
- Threshold: Minimum 40 points for auto-match without user intervention.

5. Offline Sync Protocol

To prevent data loss in basements or unstable networks:

Offline Engine: Service Workers cache assets. IndexedDB saves data.
UUID Labeling: Every sync operation generated offline is tagged with a client-side UUID.
Idempotent Backend: The bulk_sync endpoint checks UUIDs against AuditLog before applying increments, preventing double-counts.

3.1 KiB Raw Blame History