# 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
1. **Input**: Image capture or upload in the UI.
2. **Processing**: Backend receives image → calls Gemini/Claude with optimized prompts.
3. **Extraction**: Returns JSON: `name`, `part_number`, `quantity`, `category`, `specs`.
4. **Validation**: UI Wizard allows manual adjustment before finalizing.

### 3.2 Offline-First Sync Architecture
1. **Local Storage**: All writes are committed to IndexedDB (Dexie) immediately.
2. **Sync Mechanism**: Background worker identifies unsynced entries (UUID-based).
3. **Bulk Push**: Periodic attempts to push to `/sync/bulk` endpoint.
4. **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