55 lines
3.1 KiB
Markdown
55 lines
3.1 KiB
Markdown
# 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.
|