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 for inventory management featuring web administration, offline field operations (PWA), audit logging, and AI-powered label extraction.

2. Technical Stack

2.1 Backend (API & Data)

Language: Python 3.12+
Framework: FastAPI (Async ASGI)
Database: SQLite (SQLAlchemy) with WAL mode for concurrency
Validation: Pydantic v2
Auth: Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching
AI Engine: Google GenAI (Gemini 2.0 Flash) & Anthropic (Claude 3.5 Sonnet)
Logging: Python logging with rotation (10MB per file)

2.2 Frontend (Web & PWA)

Architecture: Next.js 15+ (App Router, TypeScript Strict)
Styling: Tailwind CSS v3.4 (Standard typography, normal weight only)
Icons: Lucide Icons (exclusive)
Offline Persistence: Dexie.js (IndexedDB)
Scanner: html5-qrcode (Client-side, offline)
Sync: Axios with UUID-based idempotency

2.3 Operations & Tooling

PWA: next-pwa (Service Workers + Manifest)
HTTPS Proxy: Caddy (Port 8909)
Containerization: Docker & Docker Compose
Deployment: deploy.sh (Docker) or start_server.sh (Standalone)

3. Core Business Logic

3.1 AI Extraction Pipeline

Capture/Upload image in UI.
Send to Backend → Process via Gemini (Primary) or Claude (Fallback).
Extract JSON: name, part_number, quantity, category, specs.
Validate extraction in UI wizard before saving.

3.2 Offline-First Sync

All changes saved locally to IndexedDB immediately.
Background sync attempts to push to Backend via /sync/bulk endpoint.
UUIDs ensure idempotency (no duplicate items on retry).

3.3 Audit Trail

Every modification creates a LogEntry.
Logs are immutable and stored in a separate table.
Deleting an Item preserves its AuditLog history.

4. Design & Mobile Constraints

4.1 Spacing & Layout

Container: max-w-7xl for main pages.
Responsive Spacing: space-y-3 (mobile) → space-y-6 (desktop).
Padding: p-4 (mobile) → p-8 (desktop).
Height: Avoid min-h-screen on mobile to prevent viewport overflow; use md:min-h-screen.

4.2 Typography

Readability: Standard camel/Title case.
NO UPPERCASE: Strictly forbidden in UI text.
NO BOLD: Use font-normal. Hierarchy via size (text-sm vs text-3xl) and color (text-slate-500 vs text-white).

5. Security Architecture

JWT: Stateless tokens for API auth.
LDAP: Primary source of truth for users in enterprise mode.
Password Caching: Encrypted local cache for offline authentication.
CORS: Restricted origins in production via inventory.env.

Last Updated: 2026-04-23
Version: 1.14.6

2.9 KiB Raw Blame History