# Inventory Application Requirements

## 1. Description
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. Core Constraints & System Elements

### 2.1 Main Application Server (Linux Backend)
*   **Target Environment:** Dockerized Linux Environment.
*   **Framework:** Python (FastAPI) + SQLite database.
*   **Users & Security:** Support multiple authenticated users with distinct actions.
*   **Audit Compliance:** **All operations** must maintain a strict audit log detailing who changed what and when.

### 2.2 Client Interface (PWA - Progressive Web App)
*   **Unified Interface:** A single Web Application (Next.js or similar) that is fully responsive. It functions as the administration dashboard on desktop and as a mobile application on phones/tablets.
*   **Installation:** Installed on mobile devices directly via the browser ("Add to Home Screen") to bypass App Stores. Completely managed by the main Linux Server.
*   **Offline Mode:** Service Workers and local browser storage (IndexedDB) must cache the inventory catalog, allowing offline check-ins/check-outs. Modifications are synced to the Linux server upon network reconnection.
*   **Hardware Access:** Must natively tap into the device's camera via HTML5 APIs to capture barcode data or full images.

### 2.3 Scanning & AI processing Cost-Optimization Strategy (Crucial)
*   **Routine Operations (Check-in / Check-out):** Utilize client-side, offline Javascript libraries (e.g., `html5-qrcode`) to read 1D/2D barcodes directly in the browser's camera. This executes entirely on the local device unconditionally and uses no AI cloud credits.
*   **New Item Onboarding (AI Label OCR):** When an unknown label is encountered or a specific new item is being created, the user takes a high-res photo. This photo is sent to the backend, which proxies a minimal request to a Cloud AI API (e.g., OpenAI / GPT-4 Vision).
*   **Template Extraction:** The AI performs standard OCR & structure extraction based on strict prompting templates. The parsed elements are transmitted back to the client interface.
*   **Validation Mask:** The client interface explicitly presents a selection mask. The user selects which parsed strings/fields map to specific Item properties (e.g., identifying the actual serial number while discarding vendor identifiers) before committing the Item to the database.

### 2.4 Data Models & Entities
*   **Item:** Name, Category, Labels, Quantity, Image, Barcode / SKU.
*   **Intervention:** Linked to a required items list.
*   **Audit Log:** Immutable ledger detailing CRUD operations and stock fluctuations.

### 2.5 Workflows & Reporting
*   **Reports:** Quantity aggregates across all items/categories, with historical tracking of item usage intervals (last month, last 6 months, last year).
*   **Notifications:** Alert generation when stock drops below minimum quantities.
*   **Intervention Planning:** Loading intervention lists (Text/Scanning). Check-outs must fulfill matching lists incrementally, while Check-ins reconcile unused stock.