# 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
1. Capture/Upload image in UI.
2. Send to Backend → Process via Gemini (Primary) or Claude (Fallback).
3. Extract JSON: `name`, `part_number`, `quantity`, `category`, `specs`.
4. Validate extraction in UI wizard before saving.

### 3.2 Offline-First Sync
1. All changes saved locally to IndexedDB immediately.
2. Background sync attempts to push to Backend via `/sync/bulk` endpoint.
3. 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 `config/network.yaml` (SSOT).

---

**Last Updated**: 2026-04-23  
**Version**: 1.14.19