# 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, Box Label (Association).
- **Category:** Predefined groups for organizational structure.
- **Box/Container:** A generic grouping label (box_label) that links multiple items together for rapid multi-scanning.
- **Audit Log:** Immutable ledger detailing CRUD operations and stock fluctuations, including point-in-time box associations.

## 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
- **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 Mode:** Fully automated. Cycles every 4 seconds without user intervention. Visual countdown shown in controls panel.
- **UI Layout:** Camera viewport is always unobstructed. Controls (Zoom + countdown status) are displayed in a dedicated section below the viewport.
- **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.

### 4.3 Box Labeling & Printing System (v1.5.0)
- **Local OCR Priority:** Before checking individual S/Ns, the matching engine searches for `box_label` tokens. If a box is identified:
  - Single Match: Directly opens stock adjustment.
  - Multi Match: Opens "Box Contents" selection interstitial.
- **Label Generation:** Native SVG-based Code 128 and QR generation (`lib/labels.ts`). Requires ZERO external libraries for maximum offline stability.
- **Printing Modes:**
  - @media print: Hardcoded CSS styles for 62mm x 29mm label dimensions.
  - Mobile Export: Canvas-to-PNG rasterization for sharing with Bluetooth printer roll apps.


## 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.

## 6. Automation & Versioning (`scripts/`)
- **`scripts/save_version.py`**: Implements the `save-version` AI Command Shortcut. Increments `VERSION.json` patch version, commits all staged changes, creates a snapshot branch `v.X.Y.Z`, and calls `./export_prod.sh` to generate the production bundle. Always stays on the `dev` branch.


## 7. Security & Hardening (v1.4.0)
To ensure enterprise-grade protection, the following policies are enforced:

### 7.1 Access Control & RBAC
- **Strict Separation:** Operations are divided into `user` and `admin` roles.
- **Admin Only:** Critical operations such as `DELETE /items/`, user management, and DB settings are restricted via the `auth.get_current_admin` dependency.
- **User Role:** Standard users are permitted to perform check-in/out and list inventory, but cannot delete catalog entries.

### 7.2 Brute-Force Protection
- **Rate Limiting:** Implemented via `slowapi`. The `login` endpoint is limited to **5 requests per minute** per IP to mitigate automated credential stuffing.

### 7.3 Data Privacy
- **Information Scrubbing:** Backend logs are configured to intercept and mask sensitive auth tokens or internal secrets (e.g., `JWT_SECRET_KEY`) during debug output.
- **Direct Bind LDAP:** Authentication uses direct user binding to the LDAP server, avoiding the need for a privileged service account with broad search permissions.

### 7.4 PWA Trust & Security
- **HTTPS Enforcement:** The system requires TLS (Port 3003) for camera access and secure token transmission.
- **Manifest Integrity:** A comprehensive `manifest.json` ensures the app is recognized as a trusted PWA on mobile platforms (iOS/Android).