From 748bbc301abd7bac402c2c78fc793e238c497eb8 Mon Sep 17 00:00:00 2001 From: Daniel Bedeleanu Date: Fri, 10 Apr 2026 13:35:03 +0300 Subject: [PATCH] chore: initial project scaffolding with AI rules and requirements --- AI_RULES.md | 32 ++++++++++++++++++++++++++++++++ PLAN.md | 31 +++++++++++++++++++++++++++++++ VERSION.json | 4 ++++ dev_docs/ARCHIVE_LOGS.md | 11 +++++++++++ dev_docs/PLAN_HISTORY.md | 5 +++++ dev_docs/UI_FIDELITY_SPEC.md | 12 ++++++++++++ requirements.md | 34 ++++++++++++++++++++++++++++++++++ 7 files changed, 129 insertions(+) create mode 100644 AI_RULES.md create mode 100644 PLAN.md create mode 100644 VERSION.json create mode 100644 dev_docs/ARCHIVE_LOGS.md create mode 100644 dev_docs/PLAN_HISTORY.md create mode 100644 dev_docs/UI_FIDELITY_SPEC.md create mode 100644 requirements.md diff --git a/AI_RULES.md b/AI_RULES.md new file mode 100644 index 00000000..80f375af --- /dev/null +++ b/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 (``); 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. diff --git a/PLAN.md b/PLAN.md new file mode 100644 index 00000000..6319c460 --- /dev/null +++ b/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. diff --git a/VERSION.json b/VERSION.json new file mode 100644 index 00000000..ebcf3c0f --- /dev/null +++ b/VERSION.json @@ -0,0 +1,4 @@ +{ + "version": "0.1.0", + "last_updated": "2026-04-10" +} diff --git a/dev_docs/ARCHIVE_LOGS.md b/dev_docs/ARCHIVE_LOGS.md new file mode 100644 index 00000000..0a4001ed --- /dev/null +++ b/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) diff --git a/dev_docs/PLAN_HISTORY.md b/dev_docs/PLAN_HISTORY.md new file mode 100644 index 00000000..7dbb6ef7 --- /dev/null +++ b/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)* diff --git a/dev_docs/UI_FIDELITY_SPEC.md b/dev_docs/UI_FIDELITY_SPEC.md new file mode 100644 index 00000000..d9624c70 --- /dev/null +++ b/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)* diff --git a/requirements.md b/requirements.md new file mode 100644 index 00000000..ed4ff5b9 --- /dev/null +++ b/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.