chore: initial project scaffolding with AI rules and requirements

AI_RULES.md

@@ -0,0 +1,32 @@
+# AI AGENT RULES - SINGLE SOURCE OF TRUTH
+
+This file is the single source of truth for ALL Artificial Intelligence agents working on this project (Claude, Gemini, etc.).
+Any AI or session MUST respect these mandatory rules.
+
+## General Rules
+- **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.
+
+## Implementation Completion
+- All code modifications MUST be committed in git before the task is considered finished. `VERSION.json` must be updated on EACH commit.
+- **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.
+- **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.
+- **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 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.
+- After finishing an entire job, end your final response on a separate line exactly with:
+  ```
+  ---
+  ✓ Done.
+  ```
+- Do not provide unnecessary 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 Bootstrap Icons (`<i class="bi bi-something"></i>`); never use emojis.
+- 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.

PLAN.md

@@ -0,0 +1,31 @@
+# Inventory PWA System Implementation Plan
+
+This document outlines the technical architecture for the unified Inventory System (FastAPI + PWA).
+
+## Proposed Architecture
+
+### 1. Backend Server (Linux / Docker)
+- **Framework:** Python + FastAPI
+- **Database:** PostgreSQL
+- **Key Modules:**
+  - `Items / Interventions`: Standard CRUD logic.
+  - `Audit`: Every payload that mutates data writes an immutable log row.
+  - `AI-OCR`: Endpoint integrating Google Gemini Vision API (via Google AI Studio key) for complex label extraction onboarding.
+
+### 2. Unified Web Application (PWA)
+- **Framework:** React + Next.js (or equivalent).
+- **Offline Engine:** Service Workers, IndexedDB local storage map.
+- **Desktop Mode:** Full width dashboard, management, and settings.
+- **Mobile Mode (Browser / Add to Homescreen):** Dedicated full-screen scanner using `html5-qrcode`.
+
+### 3. AI Cost Strategy
+- **Routine Scans (Check-ins/Outs):** Client-side HTML5 barcode scanner. **Cost: $0.**
+- **Label Scanning (New Item):** Proxies a request to the Gemini API to parse the SFP label into JSON template fields.
+
+## Implementation Phases
+
+- **Phase 1: Database & Backend Foundation** - Docker setup, PostgreSQL schemas, User management, and Python API structures.
+- **Phase 2: Core Inventory API** - Endpoints to Add/Remove items, offline sync-merge logic, Audit triggers.
+- **Phase 3: The PWA Frontend** - PWA manifest, offline capabilities, UI scaffolding for Desktop/Mobile.
+- **Phase 4: Client-Side Scanning** - Integration of local JS barcode reading for routine stock scanning.
+- **Phase 5: Gemini AI Vision Integration** - Server-side Gemini API integration and the text-mapping frontend view.

VERSION.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.1.0",
+  "last_updated": "2026-04-10"
+}

dev_docs/ARCHIVE_LOGS.md

@@ -0,0 +1,11 @@
+# Archive Logs
+This file contains the mandatory historical log of code, architecture, and logic modifications.
+Each entry MUST be formatted chronologically.
+
+## Log Format
+### [YYYY-MM-DD HH:MM] Feature/Modification Title
+**Purpose:** Why this was modified.
+**Modified Files:**
+- `path/to/file`
+
+**Test Results:** (if applicable)

dev_docs/PLAN_HISTORY.md

@@ -0,0 +1,5 @@
+# Plan History
+This file tracks all completed tasks and phases moved from `PLAN.md`.
+
+## Archive
+*(Moved completed components here to keep PLAN.md focused on active work)*

dev_docs/UI_FIDELITY_SPEC.md

@@ -0,0 +1,12 @@
+# 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)*

requirements.md

@@ -0,0 +1,34 @@
+# 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)
+*   **Target Environment:** Dockerized Linux Environment.
+*   **Framework:** Python (FastAPI) + PostgreSQL database.
+*   **Users & Security:** Support multiple authenticated users with distinct actions.
+*   **Audit Compliance:** **All operations** must maintain a strict audit log detailing who changed what and when.
+
+### 2.2 Client Interface (PWA - Progressive Web App)
+*   **Unified Interface:** A single Web Application (Next.js or similar) that is fully responsive. It functions as the administration dashboard on desktop and as a mobile application on phones/tablets.
+*   **Installation:** Installed on mobile devices directly via the browser ("Add to Home Screen") to bypass App Stores. Completely managed by the main Linux Server.
+*   **Offline Mode:** Service Workers and local browser storage (IndexedDB) must cache the inventory catalog, allowing offline check-ins/check-outs. Modifications are synced to the Linux server upon network reconnection.
+*   **Hardware Access:** Must natively tap into the device's camera via HTML5 APIs to capture barcode data or full images.
+
+### 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, Labels, Quantity, Image, Barcode / SKU.
+*   **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.