docs: consolidate all rules and specs into absolute sources of truth v1.2.8

PROJECT_ARCHITECTURE.md

@@ -0,0 +1,54 @@
+# 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.