83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# 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
|