tfm_ainventory/requirements.md

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)

See dev_docs/TECH_STACK.md for detailed backend specifications.

• Target Environment: Dockerized Linux Environment.
• Users & Security: Support multiple authenticated users (PBKDF2 local + optional LDAP).
• Audit Compliance: All operations maintain a strict audit log (unique UUIDs, details).

2.2 Client Interface (PWA - Progressive Web App)

See dev_docs/TECH_STACK.md for frontend libraries and architecture.

• Offline Mode: Service Workers and local browser storage (IndexedDB) must cache the inventory catalog.
• Hardware Access: Must natively tap into the device's camera via HTML5 APIs.

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 Group (Structured), Item Type (Specific), Quantity, Barcode, Part Number.
• Category: Predefined groups for organizational structure (e.g., Connectors, Tools).
• 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.