bede/tfm_ainventory
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: consolidate all rules and specs into absolute sources of truth v1.2.8

Browse Source
This commit is contained in:
Daniel Bedeleanu
2026-04-11 12:03:27 +03:00
parent 432cd28ca5
commit 0a9ea0f575
10 changed files with 112 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
AI_RULES.md
View File

@@ -1,44 +1,42 @@
# AI AGENT RULES - SINGLE SOURCE OF TRUTH # AI AGENT RULES - MANDATORY ENTRY POINT
This file is the single source of truth for ALL Artificial Intelligence agents working on this project (Claude, Gemini, etc.). **READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK.**
Agent-specific instructions are located in `GEMINI.md` and `CLAUDE.md`. This is the **Single Source of Truth** for ALL Artificial Intelligence agents (Claude, Gemini, etc.) working on this project.
Any AI or session MUST respect these mandatory rules. For technical architecture, data models, and stack details, refer to [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md).
## General Rules ## 1. Multi-AI Coordination & Memory
- **UI & Code Language**: All web interfaces, functions, variables, and any text inside the application MUST BE DIRECTLY AND ONLY IN ENGLISH.
- **Communication Language**: Conversation with the user will be in Romanian or English, preferably Romanian.
## Multi-AI Coordination & Handover
- **MANDATORY STARTUP**: Every AI session MUST first read `dev_docs/SESSION_STATE.md` to understand current context. - **MANDATORY STARTUP**: Every AI session MUST first read `dev_docs/SESSION_STATE.md` to understand current context.
- **MANDATORY HANDOVER**: At the end of every task/session, create or update a handover note in `dev_docs/SESSION_STATE.md`. Specify: **Active AI**, **Current Status**, **Technical Context** (details not in code), and **Next Steps**. - **MANDATORY HANDOVER**: At the end of every task/session, update the handover note in `dev_docs/SESSION_STATE.md`. Specify: **Active AI**, **Current Status**, **Technical Context**, and **Next Steps**.
- **ARCHIVAL RULE**: To prevent `SESSION_STATE.md` from bloating, incoming AI agents MUST move all content of the *previous* session handover into the top of `dev_docs/SESSION_HISTORY.md` before writing their own new state. This keeps `SESSION_STATE.md` focused only on the *active* session. - **ARCHIVAL RULE**: Before writing new state, move all content of the *previous* session handover into the top of `dev_docs/SESSION_HISTORY.md` to prevent bloat.
- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it according to `SESSION_STATE.md`. - **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it.
## Implementation Completion ## 2. Global Operational Laws
- All code modifications MUST be committed in git before the task is considered finished. `VERSION.json` must be updated on EACH commit. - **STRICT ENGLISH POLICY**: All web interfaces, code, variables, scripts, and documentation MUST BE DIRECTLY AND ONLY IN ENGLISH. If you find Romanian text in code, translate it immediately.
- **MANDATORY GIT RULE:** Never push to remote unless explicitly requested by the user. Only commit locally with proper messages. Always assume the user will handle all `git push` operations. If a task requires pushing, ask for explicit permission first. - **COMMUNICATION LANGUAGE**: Conversation with the user will be in Romanian or English (preferably Romanian).
- **GIT BINARY PATH**: On this macOS environment, the system `git` (in `/usr/bin/git`) is often broken due to `xcode-select` issues. ALWAYS use the binary path stored in `.git_path` at the project root for all Git operations. - **GIT BINARY PATH**: On this macOS environment, the system `git` is often broken. ALWAYS use the binary path stored in `.git_path` at the project root for all Git operations.
- **GIT BRANCHING STRUCTURE**: - **COMMIT & PUSH STRICT RULE**:
- The main stable branch is `master`. - Never push to remote (`git push`) or use force flags (`--hard`, `--force`) unless explicitly requested.
- All active development MUST occur in the `dev` branch. - Always update `VERSION.json` on every commit.
- Every major version MUST have its own dedicated archival branch named `vX` (e.g., `v1`, `v2`) which copies the state of the major release. - Do NOT add AI co-author signatures (e.g., `Co-Authored-By: AI...`) to commit messages.
- **MANDATORY GIT RULE**: NO AI is allowed to write in git commits that it is the author or co-author (e.g., DO NOT add texts like `Co-Authored-By: AI...`). Commits should only contain technical messages. - Branching: `master` (stable), `dev` (active development), `vX` (archival releases).
- **MANDATORY LOGGING**: Any modification of code, architecture, or logic MUST be documented in `dev_docs/ARCHIVE_LOGS.md` at the end of the task. The log must include modified files, purpose of modification, and (if applicable) test results. - **MANDATORY LOGGING**: Document coding/architecture changes in `dev_docs/ARCHIVE_LOGS.md` at the end of the task.
- **MANDATORY PLAN ARCHIVING**: Once a phase or task is confirmed as completed and verified, the Architect (Gemini/AI) MUST move these entries from `PLAN.md` into `dev_docs/PLAN_HISTORY.md`. This maintains the active plan's focus and prevents document bloat. - **TRIPLE CONFIRMATION (Safe Forget)**: You cannot delete a physical location, item, or critical entity without explicit user permission three times.
- After finishing an entire job, end your final response on a separate line exactly with:
## 3. UI/UX Fidelity Specifications
- **Fidelity First**: Never simplify the UI unless asked. Density and aesthetics must remain "Premium".
- **Styling**: Tailwind CSS. Font weights/spacing must be consistent (Inter/Roboto).
- **Readability**: NO `uppercase` or `tracking-widest` styles. Use standard camel/Title case.
- **Icons**: Use **Lucide Icons** exclusively. NO emojis.
- **Interactive Affordance**: All select/dropdown boxes MUST have a `ChevronDown` icon. Masked passwords should have reduced opacity (`text-white/50`).
- **Iconography Standardization**:
- **Categories**: ALWAYS use `Layers` (Color: `text-primary`).
- **Item Types**: ALWAYS use `Package` (Color: `text-green-500`).
## 4. End of Session Protocol
- Once a phase/task from `PLAN.md` is completed and verified, move that entry into `dev_docs/PLAN_HISTORY.md`.
- After finishing an entire job (including updating session state, architecture logs, and versioning), end your final response on a separate line exactly with:
``` ```
--- ---
✓ Done. ✓ Done.
``` ```
- Do not provide unnecessary summaries of the code. - Do not provide unnecessary verbatim summaries of the code.
## Triple Confirmation & Safety Limits
- **Safe Forget**: You cannot delete a physical location, item, or critical entity without a triple confirmation mechanism.
- **No Force Operations**: Never use destructive flags (e.g., `git reset --hard`, `git push --force`, `rm -rf`) without explicit user permission.
## UI/UX & Documentation Rules
- **STRICT ENGLISH POLICY**: ANY TEXT within the application (documentation, scripts, CLI, UI, internal comments, logs, etc.) MUST be strictly in English. NO Romanian characters (ăâîșț) or words are allowed in the repository.
- **MANDATORY TRANSLATION**: Any Romanian text found during an AI session (in any file) MUST be translated to English immediately.
- Use Lucide Icons (standard React components); never use emojis or legacy Bootstrap icons.
- The UI must remain fully functional offline (no external CDNs).
- **MANDATORY UI FIDELITY**: Any modification to UI components (headers, banners, cards, buttons) MUST comply with the specifications in `dev_docs/UI_FIDELITY_SPEC.md` to prevent regressions. All agents MUST read that document before modifying frontend code.

29
GEMINI.md
View File

@@ -1,29 +0,0 @@
# GEMINI AGENT CONTEXT (Memory & Rules)
This file is the specific entry point for **Gemini** (Antigravity). It summarizes critical project knowledge and operational rules to ensure continuity and high-fidelity output.
## 🚀 Quick Access
- **Primary Rules:** [AI_RULES.md](AI_RULES.md)
- **Technical Stack:** Section 2 in [requirements.md](requirements.md)
- **Active Plan:** [PLAN.md](PLAN.md)
- **Session State:** [dev_docs/SESSION_STATE.md](dev_docs/SESSION_STATE.md)
- **UI Specs:** [dev_docs/UI_FIDELITY_SPEC.md](dev_docs/UI_FIDELITY_SPEC.md)
## 🏗 Operations & Tooling
- **Git Binary:** Path is in `.git_path` (Relative to project root).
- **Versioning:** Always update `VERSION.json` on every commit.
- **Logbook:** Update `dev_docs/ARCHIVE_LOGS.md` after every feature/fix.
- **Dev Servers:** Frontend (Port 3000), Backend (Port 8000 via `./start_server.sh`).
## 🧠 Project Specific Knowledge
- **Iconography System:**
- **Categories:** Always use `Layers` (Primary color: `text-primary`).
- **Item Types:** Always use `Package` (Color: `text-green-500`).
- **Indicators:** Use `ChevronDown` for selects/interactive dropdowns.
- **Offline Protocol:** Users can log in while offline if they have authenticated via LDAP at least once before (hash is cached locally).
- **Naming Policy:** Application text MUST be English. User conversation is Romanian.
## 📜 Personal Directives
1. **Fidelity First:** Never simplify UI unless explicitly asked. Density and aesthetics must remain "Premium".
2. **Case Sensitivity:** Backend searches (SQLite) are often case-sensitive; front-end should normalize to UPPERCASE for barcodes/PNs.
3. **Commit Messages:** Use conventional commits (`feat:`, `fix:`, `style:`, etc.).

43
PLAN.md
View File

@@ -1,44 +1,13 @@
# Inventory PWA System Architecture & Implementation Plan # Active Development Plan
This document defines the technical architecture and rules for the InventoryAI System (2026 Edition). This document tracks the immediate implementation checklist. For overarching design and constraints, see [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md).
## 1. Core Architecture
See the detailed [dev_docs/TECH_STACK.md](dev_docs/TECH_STACK.md) for official framework, database, and library versions.
Summary: FastAPI / Python 3.12+ (Backend) & Next.js 15+ PWA (Frontend). Sync via Dexie.js (client side) and SQL sync logic (v1.2.4).
## 2. AI Intelligence Strategy (Critical)
### 2.1 AI Usage Policy
- **New Item Onboarding:** AI-OCR is permitted. It analyzes complex label photos (SFP, hardware specs) and maps them to JSON fields.
- **Routine Operations (Check-in/Out/Audit):** **AI IS STRICTLY FORBIDDEN.**
- Use local barcode/QR scanning only.
- If a label is not recognized locally, the user is prompted to start the "AI Onboarding Assistant".
- Goal: $0 cost for 99% of daily operations.
### 2.2 Modular AI Providers Architecture
Located in `backend/ai/`, the system supports multiple providers through a managed orchestrator:
- **Provider Modules:** `gemini.py`, `claude.py`, etc.
- **SDK Update (v2):** Switched to `google-genai` (v2) for improved stability and response parsing.
- **Model Hardcoding Power:** Switched from dynamic discovery to fixed high-speed models (`gemini-2.0-flash`) for sub-second responses on cellular networks.
### 2.3 Hybrid Sync & Deduplication (New)
To ensure zero data loss during unstable mobile sessions:
- **UUID Labeling:** Every sync operation generated on a mobile device is tagged with a client-side UUID.
- **Idempotent Backend:** The `bulk_sync` endpoint checks UUIDs against `AuditLog` before applying increments, preventing double-counts.
## 3. Data Integrity & Audit
- **Immutable Audit Log:** Every change (Add, Remove, Edit) is logged with a timestamp, action, and previous/new state.
- **Validation Mask:** AI-extracted data is NEVER saved directly. It is presented to a human user in a validation UI for final confirmation.
## 4. Implementation Status
## Implementation Status
- [x] **Phase 1: Backend Foundation** (FastAPI, SQLite, Models). - [x] **Phase 1: Backend Foundation** (FastAPI, SQLite, Models).
- [x] **Phase 2: Modular AI Integration** (Gemini & Claude support, v2 SDK). - [x] **Phase 2: Modular AI Integration** (Gemini support, v2 SDK).
- [x] **Phase 3: AI Onboarding UI** (Validation Mask, Camera/Upload integration). - [x] **Phase 3: AI Onboarding UI** (Validation Mask, Camera integration).
- [x] **Phase 4: Offline Synchronization** (Deduplicated Dexie -> SQL sync logic). - [x] **Phase 4: Offline Synchronization** (Deduplicated Dexie -> SQL sync logic).
- [x] **Phase 5: Inventory Trash Management** (Waste/Discard/Damage workflow). - [x] **Phase 5: Inventory Trash Management** (Waste/Discard/Damage workflow).
- [ ] **Phase 6: Audit Log Dashboard UI** (Visual historical interventions). - [ ] **Phase 6: Audit Log Dashboard UI** (Visual historical interventions).
## 5. Security & Infrastructure *(Note: Completed phases are periodically moved to `dev_docs/PLAN_HISTORY.md` according to AI_RULES)*
- **Unified SSL Proxy:** Integrated `local-ssl-proxy` for HTTPS access (Camera/Mic) on port 3003.
- **VENV Isolation:** Automated `.venv` management in `start_server.sh`.

54
PROJECT_ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,54 @@
# 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 to maintain an inventory of "items" and their quantities, inclusive of a web administration interface, offline field operations, audit logging, and AI-powered label extraction functionalities.
## 2. Technical Stack
### 2.1 Backend (API & Data)
- **Language:** Python 3.12+ (Optimized for performance and type safety)
- **Framework:** FastAPI (Async ASGI)
- **Database:** SQLite (SQLAlchemy) - Local file-based persistence
- **Validation:** Pydantic v2
- **Auth:** Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching
- **AI Engine:** Google GenAI SDK (Gemini 2.0 Flash) - Location: `backend/ai/`
### 2.2 Frontend (Web & PWA)
- **Architecture:** Next.js 15+ (App Router)
- **Styling:** Tailwind CSS (Readability-first config)
- **Icons:** Lucide Icons (React components)
- **Offline persistence:** Dexie.js (IndexedDB wrapper)
- **Scanner:** `html5-qrcode` (Client-side, offline-only)
- **Sync:** Axios with bulk-sync idempotency (UUID-based)
### 2.3 Operations & Tooling
- **PWA Deployment:** `next-pwa` (Service Workers + Manifest.json)
- **HTTPS Proxy:** `local-ssl-proxy` (Required for mobile camera access, Port 3003)
- **Servers:** Frontend (`npm run dev` on 3000), Backend (`./start_server.sh` on 8000)
## 3. Data Models & Entities
- **Item:** Name, Category Group (Structured), Item Type (Specific), Quantity, Barcode, Part Number.
- **Category:** Predefined groups for organizational structure.
- **Intervention:** Linked to a required items list.
- **Audit Log:** Immutable ledger detailing CRUD operations and stock fluctuations.
## 4. Scanning & Optimization Strategy (Crucial)
### 4.1 AI Usage Policy
- **Routine Operations (Check-in/Out):** Executes entirely on the local device unconditionally using `html5-qrcode` ($0 cost). No AI is allowed here.
- **New Item Onboarding (AI Label OCR):** Uses cloud AI (`gemini-2.0-flash`). The user takes a photo, AI extracts data based on strict templates.
- **Validation Mask:** AI-extracted data is NEVER saved directly. It is presented in a validation UI for human confirmation.
### 4.2 Scanner Technical Specs (FROZEN)
- **Hardware Access:** Direct `MediaStreamTrack` access. Zoom cycle: 1x -> 2x -> Max/2 -> Max.
- **Image Pre-processing:** Rescaling (1200px), 60% Center Crop, Grayscale/Contrast filters, JPEG (`0.85` quality).
- **OCR Matching Engine (`page.tsx`):**
- Noise Filtering: Ignores `< 3` chars, decimals, and dates.
- Scoring: Exact S/N (+500), Exact P/N (+200), Token match (+50), Category match (+20).
- Threshold: Minimum **40 points** for auto-match without user intervention.
## 5. Offline Sync Protocol
To prevent data loss in basements or unstable networks:
- **Offline Engine:** Service Workers cache assets. IndexedDB saves data.
- **UUID Labeling:** Every sync operation generated offline is tagged with a client-side UUID.
- **Idempotent Backend:** The `bulk_sync` endpoint checks UUIDs against `AuditLog` before applying increments, preventing double-counts.

11
VERSION.json
View File

@@ -1,8 +1,9 @@
{ {
"version": "1.2.7", "version": "1.2.8",
"last_build": "2026-04-11-1216", "last_build": "2026-04-11-1225",
"commit": "e8f7d", "commit": "ab3c9",
"changelog": [ "changelog": [
"v1.2.8: Absolute Documentation Consolidation (Unified ARCHITECTURE and AI_RULES)",
"v1.2.7: Documentation Refactor: Created TECH_STACK.md for SSOT and removed absolute paths", "v1.2.7: Documentation Refactor: Created TECH_STACK.md for SSOT and removed absolute paths",
"v1.2.6: Hotfix - Added missing icon imports (Layers, ChevronDown)", "v1.2.6: Hotfix - Added missing icon imports (Layers, ChevronDown)",
"v1.2.5: Synchronized icons across UI (Layers for Categories, Package for Item Types)", "v1.2.5: Synchronized icons across UI (Layers for Categories, Package for Item Types)",
@@ -10,8 +11,6 @@
"v1.2.3: System-wide UI consistency (standardized font sizes, removed uppercase)", "v1.2.3: System-wide UI consistency (standardized font sizes, removed uppercase)",
"v1.2.2: UI Readability refactor (Removed uppercase/tracking, increased font sizes)", "v1.2.2: UI Readability refactor (Removed uppercase/tracking, increased font sizes)",
"v1.2.1: Git path persistence, master/dev/vX branching, and UI case-sensitivity fix", "v1.2.1: Git path persistence, master/dev/vX branching, and UI case-sensitivity fix",
"v1.2.0: Structured category management with grouping support", "v1.2.0: Structured category management with grouping support"
"v1.1.0: Multi-user auth & LDAP framework integration",
"v1.0.0: Initial PWA inventory launch"
] ]
} }

13
dev_docs/ARCHIVE_LOGS.md
View File

@@ -1,3 +1,16 @@
### [2026-04-11 12:25] v1.2.8: Absolute Documentation Consolidation
**Purpose:** Restructured all project documentation to completely eliminate redundancy and establish clear "Single Source of Truth" boundaries for humans and AI agents.
**Actions:**
- Created `PROJECT_ARCHITECTURE.md` uniting business requirements, tech stack, data models, and specific OCR algorithms.
- Unified all AI operational rules, constraints, and UI fidelities strictly inside `AI_RULES.md`.
- Removed redundant, overlapping files (`GEMINI.md`, `requirements.md`, `TECH_STACK.md`, `UI_FIDELITY_SPEC.md`, `SCANNER_LOGIC_SPEC.md`).
- Stripped `PLAN.md` down to just the active checklist.
**Modified Files:**
- `PROJECT_ARCHITECTURE.md` (New)
- `AI_RULES.md`
- `PLAN.md`
- `VERSION.json`
### [2026-04-11 12:15] v1.2.7: Documentation Refactor & Portability ### [2026-04-11 12:15] v1.2.7: Documentation Refactor & Portability
**Purpose:** Consolidated technical stack information into a single source of truth (`dev_docs/TECH_STACK.md`) and removed absolute paths from all AI-facing documents to ensure the project can be moved across environments without breaking references. **Purpose:** Consolidated technical stack information into a single source of truth (`dev_docs/TECH_STACK.md`) and removed absolute paths from all AI-facing documents to ensure the project can be moved across environments without breaking references.
**Modified Files:** **Modified Files:**

36
dev_docs/SCANNER_LOGIC_SPEC.md
View File

@@ -1,36 +0,0 @@
# TFM aInventory - Scanner Technical Specification (v1.2)
This document defines the "Frozen" parameters for the scanner component. Do NOT modify these values without explicit user approval.
## 1. Hardware Access
- **API**: Direct `MediaStreamTrack` access for high-performance camera control.
- **Zoom**: Dynamic detection of `capabilities.zoom.max`.
- **Zoom Cycle**: 1x -> 2x -> Max/2 -> Max.
## 2. Image Pre-processing (The OCR "Secret Sauce")
Before being sent to Tesseract.js, every frame undergoes these transformations:
- **Rescaling**: Fixed canvas width of **1200px** (Optimal for Mobile RAM/Accuracy).
- **Cropping**: **60% Center Crop** of the video stream (forces focus & removes peripheral noise).
- **Filters**: `grayscale(100%) contrast(180%) brightness(105%)`.
- **Format**: High-quality JPEG (`0.85` quality) via `toDataURL`.
## 3. OCR Matching Engine (page.tsx)
- **Sanitization**: Text normalized to UPPERCASE, non-alphanumeric replaced with spaces.
- **Noise Filtering**:
- Tokens < 3 chars ignored.
- Decimals (e.g., `0.11`, `0.18`) ignored via regex: `/^\d+\.\d+$/`.
- Dates (e.g., `2024-07-25`) ignored via regex: `/^\d{2,4}-\d{2}-\d{2}$/`.
- **Scoring System**:
- **Exact Serial Number Match**: +500 points (Instant Match).
- **Exact Part Number Match**: +200 points.
- **Token match (e.g., "LC" in "LC/UPC")**: +50 points.
- **Category Match**: +20 points.
- **Threshold**: Minimum **40 points** required for automatic match without user intervention.
## 4. UI/UX Flow
1. **Auto-Match**: Attempt to identify item immediately from raw text.
2. **Interactive Selection (Fallback)**: If match confidence is low, freeze frame and show clickable bounding boxes for manual word selection.
---
*Created: 2026-04-10*
*Status: FROZEN*

25
dev_docs/TECH_STACK.md
View File

@@ -1,25 +0,0 @@
# TECHNICAL STACK - SINGLE SOURCE OF TRUTH
This document defines the official technology stack for the Inventory System. All components must adhere to these versions and libraries.
## 🟢 Backend (API & Data)
- **Language:** Python 3.12+ (Optimized for performance and type safety)
- **Framework:** [FastAPI](https://fastapi.tiangolo.com/) (Async ASGI)
- **Database:** SQLite (SQLAlchemy) - Local file-based persistence
- **Validation:** Pydantic v2
- **Auth:** Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching (v1.2.4)
- **AI Engine:** Google GenAI SDK (Gemini 2.0 Flash) - Location: `backend/ai/`
## 🔵 Frontend (Web & PWA)
- **Architecture:** [Next.js](https://nextjs.org/) 15+ (App Router)
- **Styling:** Tailwind CSS (Readability-first config: No uppercase/tracking-widest)
- **Icons:** [Lucide Icons](https://lucide.dev/) (React components)
- **Offline persistence:** [Dexie.js](https://dexie.org/) (IndexedDB wrapper)
- **Scanner:** `html5-qrcode` (Client-side, offline-only)
- **Sync:** Axios with bulk-sync idempotency (UUID-based)
## 🏗 Operations & Tooling
- **PWA Deployment:** `next-pwa` (Service Workers + Manifest.json)
- **HTTPS Proxy:** `local-ssl-proxy` (Required for mobile camera access)
- **Version Control:** Git (Local-first, path in `.git_path`)
- **Isolation:** Python `.venv` and Node `node_modules`

12
dev_docs/UI_FIDELITY_SPEC.md
View File

@@ -1,12 +0,0 @@
# UI Fidelity Specification
This document details the mandatory visual and structural specifications for UI components (headers, banners, cards, buttons) in the unified PWA interface.
## 1. General Principles
- Use TailwindCSS (or equivalent local vanilla CSS framework established).
- No emojis; strictly Bootstrap Icons.
- Standard spacing, consistent font weight (Inter or Roboto).
- Responsive: Viewport scaling for both Desktop dashboard and Mobile full-screen scanning modes.
## 2. Specific Components
*(To be populated as components are developed)*

34
requirements.md
View File

@@ -1,34 +0,0 @@
# Inventory Application Requirements
## 1. Description
A unified system to maintain an inventory of "items" and their quantities, inclusive of a web administration interface, offline field operations, audit logging, and AI-powered label extraction functionalities.
## 2. Core Constraints & System Elements
### 2.1 Main Application Server (Linux Backend)
See [dev_docs/TECH_STACK.md](dev_docs/TECH_STACK.md) for detailed backend specifications.
- **Target Environment:** Dockerized Linux Environment.
- **Users & Security:** Support multiple authenticated users (PBKDF2 local + optional LDAP).
- **Audit Compliance:** All operations maintain a strict audit log (unique UUIDs, details).
### 2.2 Client Interface (PWA - Progressive Web App)
See [dev_docs/TECH_STACK.md](dev_docs/TECH_STACK.md) for frontend libraries and architecture.
- **Offline Mode:** Service Workers and local browser storage (IndexedDB) must cache the inventory catalog.
- **Hardware Access:** Must natively tap into the device's camera via HTML5 APIs.
### 2.3 Scanning & AI processing Cost-Optimization Strategy (Crucial)
* **Routine Operations (Check-in / Check-out):** Utilize client-side, offline Javascript libraries (e.g., `html5-qrcode`) to read 1D/2D barcodes directly in the browser's camera. This executes entirely on the local device unconditionally and uses no AI cloud credits.
* **New Item Onboarding (AI Label OCR):** When an unknown label is encountered or a specific new item is being created, the user takes a high-res photo. This photo is sent to the backend, which proxies a minimal request to a Cloud AI API (e.g., OpenAI / GPT-4 Vision).
* **Template Extraction:** The AI performs standard OCR & structure extraction based on strict prompting templates. The parsed elements are transmitted back to the client interface.
* **Validation Mask:** The client interface explicitly presents a selection mask. The user selects which parsed strings/fields map to specific Item properties (e.g., identifying the actual serial number while discarding vendor identifiers) before committing the Item to the database.
### 2.4 Data Models & Entities
* **Item:** Name, Category Group (Structured), Item Type (Specific), Quantity, Barcode, Part Number.
* **Category:** Predefined groups for organizational structure (e.g., Connectors, Tools).
* **Intervention:** Linked to a required items list.
* **Audit Log:** Immutable ledger detailing CRUD operations and stock fluctuations.
### 2.5 Workflows & Reporting
* **Reports:** Quantity aggregates across all items/categories, with historical tracking of item usage intervals (last month, last 6 months, last year).
* **Notifications:** Alert generation when stock drops below minimum quantities.
* **Intervention Planning:** Loading intervention lists (Text/Scanning). Check-outs must fulfill matching lists incrementally, while Check-ins reconcile unused stock.