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 (Ports 8918/8919)
Containerization: Docker & Docker Compose
Deployment: deploy.py (Docker) or run_standalone.py (Standalone)
Configuration: Domain-specific YAML (config/) with network.yaml as SSOT.

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 (Industrial Brutalism)

4.1 Spacing & Layout

Container: max-w-7xl for main pages.
Responsive Spacing: p-4 (mobile) → p-8 (desktop) with space-y-4 → space-y-6.
Shapes: Strictly Sharp (0px) corners globally. No rounded borders.
Unified Headers: Icon box (p-4 bg-primary/10 border-primary/20) + Title (text-3xl font-normal).

4.2 Typography & Colors

Palette (Obsidian & Amber):
- Background: Deep Obsidian (#0c1322)
- Primary: Industrial Amber (#ffc174)
- Borders: Tactical Charcoal (#a08e7a)
Fonts: Space Grotesk (Headlines/Data) & Inter (Body).
NO UPPERCASE: Strictly forbidden in all UI contexts.
NO BOLD: Strictly forbidden. Use font-normal throughout. Hierarchy via size and color only.
StatCards: Numeric values must match label text size (e.g., text-base md:text-lg).

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 config/network.yaml (SSOT).

Last Updated: 2026-04-23
Version: 1.14.19

3.4 KiB Raw Blame History