TFM aInventory - System Architecture

This document defines the technical architecture, business requirements, and core logic of the system. For engineering and design standards, refer to CODING_STANDARDS.md and DESIGN_SYSTEM.md.

1. Application Overview

A unified system for inventory management featuring web administration, offline-first field operations (PWA), and AI-powered data extraction from labels.

2. Tech Stack Summary

Backend: FastAPI (Python 3.12+), SQLite (WAL mode).
Frontend: Next.js 15+ (TypeScript), Dexie.js (IndexedDB).
AI: Gemini 2.0 Flash (Primary), Claude 3.5 Sonnet (Fallback).
Operations: Docker, Caddy (Reverse Proxy).

3. Core Business Logic

3.1 AI Extraction Pipeline

Input: Image capture or upload in the UI.
Processing: Backend receives image → calls Gemini/Claude with optimized prompts.
Extraction: Returns JSON: name, part_number, quantity, category, specs.
Validation: UI Wizard allows manual adjustment before finalizing.

3.2 Offline-First Sync Architecture

Local Storage: All writes are committed to IndexedDB (Dexie) immediately.
Sync Mechanism: Background worker identifies unsynced entries (UUID-based).
Bulk Push: Periodic attempts to push to /sync/bulk endpoint.
Idempotency: UUIDs prevent duplicate records on retry.

3.3 Audit Trail System

Every modification creates an immutable LogEntry.
Audit logs are decoupled from item deletion; history is preserved even if the item is removed.

4. Configuration Architecture

The system uses domain-specific YAML files located in config/:

network.yaml: SSOT for hostnames, ports, and CORS origins.
secrets.yaml: JWT keys, API keys (never committed).
backend.yaml: Database and performance tuning.

5. Security Architecture

Authentication: Hybrid LDAP + Local fallback.
Authorization: Role-based access (Admin for destructive actions).
Encryption: JWT for stateless sessions, PBKDF2 for password hashing.
CORS: Enforced via config/network.yaml.

Last Updated: 2026-04-26
Version: 1.15.0

2.1 KiB Raw Blame History