tfm_ainventory/PROJECT_ARCHITECTURE.md

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) & Anthropic SDK (Claude 3.5 Sonnet) - Location: backend/ai/
• Testing: Pytest (Unit & Integration) - Location: backend/tests/

2.2 Frontend (Web & PWA)

• Architecture: Next.js 15+ (App Router)
• Styling: Tailwind CSS (Readability-first config, mobile-first responsive)
• Icons: Lucide Icons (React components)
• Components:
  • StatCard (v1.9.21+): Responsive stat display component for mobile/desktop
    • Two-column flexbox layout (label left, number right)
    • Responsive font sizing with Tailwind breakpoints (text-sm→md, text-lg→xl)
    • Label truncation with ellipsis for overflow handling
    • Accessibility: role="status", aria-hidden on decorative icons
• Offline persistence: Dexie.js (IndexedDB wrapper)
• Scanner: html5-qrcode (Client-side, offline-only)
• Sync: Axios with bulk-sync idempotency (UUID-based)
• Testing: Vitest (React Hook Testing) - Location: frontend/tests/

2.3 Operations & Tooling

• PWA Deployment: next-pwa (Service Workers + Manifest.json)
• HTTPS Proxy: caddy or local-ssl-proxy (Port 8909)
• Servers: Frontend (Port 8907), Backend (Port 8906)
• Configuration: Centrally managed via root inventory.env (Network/CORS/API Keys), config/ directory (LDAP, Caddyfile), and a dynamic ConfigManager (backend/config_manager.py) for runtime environment and AI provider settings.

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 or claude-3-5-sonnet). The user takes a photo, AI extracts data based on strict templates.
• AI Provider Selection (v1.9.23): Administrators can choose between Gemini and Claude via the Admin Dashboard. API keys are managed securely in the environment.
• AI Box Discovery Mode (v1.6.0): Supports specialized mode="box" prompt that focuses exclusively on prominent container names/hand-written labels, ignoring technical spec noise.
• 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.
• Targeted Field Scanning (v1.6.0): UI allows "locking" the scanner focus to a specific input field (e.g., box_label). The OCR result is then redirected to state without performing regular item lookup.

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 CORS & Origin Policy (v1.9.18)

• Automatic Discovery: The system detects local LAN IP and automatically authorizes it.
• Generic Expansion: Use EXTRA_ALLOWED_ORIGINS for Tailscale or VPN IPs. The system automatically expands each IP into a set of authorized Origins (http/8916, https/8918, https/8919).
• 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.
• Cryptographic Credential Caching: To support offline operations, the system caches a PBKDF2-HMAC-SHA256 hash of the user's Enterprise credentials upon successful online login. Plain text passwords are NEVER stored.

7.4 PWA Trust & Security

• HTTPS Enforcement: The system requires TLS (Port 8909) 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).

7.5 Git Infrastructure (Linux Native)

All git operations use the standard git command available in system PATH. On Linux systems, this is reliably provided by the git package via the system package manager.

8. Multi-AI Engine & Dynamic Configuration (v1.9.23)

To enhance extraction flexibility and system resilience:

• Unified AI Core: The backend uses an abstraction layer to handle multiple AI providers (Gemini and Claude).
• Dynamic Configuration: System settings (AI Provider, API Keys, Backup Policies) are managed via backend/config_manager.py, allowing real-time updates without restarting the container.
• Admin Standardization: The Admin Dashboard features a standardized configuration UI with secure field masking for sensitive credentials.
• Architectural Modularization (v1.10.0):
  • Frontend: The monolithic Admin Dashboard has been decomposed into domain-specific components: IdentityManager, DatabaseManager, LdapManager, AiManager, and CategoryManager.
  • Logic: Business logic is centralized in the useAdmin custom React hook, ensuring clean separation of concerns.
  • Backend: Administrative endpoints are split into the backend/routers/admin/ package, with specialized routers for backups and config.
  • Stability: Docker builds are secured against lockfile mismatches by enforcing strict dependency synchronization.
• Verification Infrastructure: A dual-layer testing suite is implemented: Pytest for backend integration (using in-memory SQLite and mocked auth) and Vitest for frontend logic validation.
• Frontend Stabilization (v1.10.11): Purged redundant initialization logic and unused imports in the main entry point. Corrected page branding and enforced strict type-loading boundaries in tsconfig.json to ensure zero-error production builds.
• Frontend Quality Audit (v1.10.15): Comprehensive frontend audit completed (14/20 → 17+/20). Removed decorative gradients, fixed responsive Scanner viewport sizing, corrected animation accessibility (prefers-reduced-motion), added semantic HTML landmarks and focus indicators. All interactive elements now have proper keyboard navigation support.