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) + PostgreSQL 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.

3.1 KiB Raw Blame History