From 432cd28ca5f5003f86df1a9ff6a53ee3e511023f Mon Sep 17 00:00:00 2001 From: Daniel Bedeleanu Date: Sat, 11 Apr 2026 11:57:13 +0300 Subject: [PATCH] docs: refactor documentation for portability and SSOT v1.2.7 --- AI_RULES.md | 3 ++- GEMINI.md | 29 +++++++++++++++++++++++++++++ PLAN.md | 15 ++------------- VERSION.json | 7 ++++--- dev_docs/ARCHIVE_LOGS.md | 14 ++++++++++---- dev_docs/SESSION_HISTORY.md | 15 +++++++++++++++ dev_docs/SESSION_STATE.md | 16 +++++++++------- dev_docs/TECH_STACK.md | 25 +++++++++++++++++++++++++ requirements.md | 15 +++++++-------- 9 files changed, 103 insertions(+), 36 deletions(-) create mode 100644 GEMINI.md create mode 100644 dev_docs/TECH_STACK.md diff --git a/AI_RULES.md b/AI_RULES.md index 82208913..b8d2a50e 100644 --- a/AI_RULES.md +++ b/AI_RULES.md @@ -1,6 +1,7 @@ # 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.). +Agent-specific instructions are located in `GEMINI.md` and `CLAUDE.md`. Any AI or session MUST respect these mandatory rules. ## General Rules @@ -38,6 +39,6 @@ Any AI or session MUST respect these mandatory rules. ## 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. +- 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. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..0f229801 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,29 @@ +# 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.). diff --git a/PLAN.md b/PLAN.md index 35f8b727..0b8ee28c 100644 --- a/PLAN.md +++ b/PLAN.md @@ -3,19 +3,8 @@ This document defines the technical architecture and rules for the InventoryAI System (2026 Edition). ## 1. Core Architecture - -### 1.1 Backend (Python 3.14+) -- **Framework:** FastAPI -- **Database:** SQLite (SQLAlchemy) - chosen for local performance and simplicity. -- **Organization:** Modular design with separate routers for Items and Operations. - -### 1.2 Frontend (Next.js 15+ PWA) -- **State Management:** React Hooks + Dexie.js (IndexedDB wrapper). -- **Offline Engine:** - - Service Workers for asset caching. - - IndexedDB for local data persistence. - - Sync mechanism: Local changes are buffered and pushed to backend when online. -- **Scanner:** `html5-qrcode` for standard barcode/QR detection (Local-only). +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) diff --git a/VERSION.json b/VERSION.json index 76911222..6e4d91bb 100644 --- a/VERSION.json +++ b/VERSION.json @@ -1,8 +1,9 @@ { - "version": "1.2.6", - "last_build": "2026-04-11-1206", - "commit": "d9e2a", + "version": "1.2.7", + "last_build": "2026-04-11-1216", + "commit": "e8f7d", "changelog": [ + "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.5: Synchronized icons across UI (Layers for Categories, Package for Item Types)", "v1.2.4: Offline LDAP auth support and UI affordance improvements (Dropdown chevrons, soft password dots)", diff --git a/dev_docs/ARCHIVE_LOGS.md b/dev_docs/ARCHIVE_LOGS.md index 82cfc3cc..f416567b 100644 --- a/dev_docs/ARCHIVE_LOGS.md +++ b/dev_docs/ARCHIVE_LOGS.md @@ -1,10 +1,16 @@ -### [2026-04-11 12:05] v1.2.6: Hotfix - Missing Icon Imports -**Purpose:** Fixed `ReferenceError: Layers is not defined` and `ChevronDown is not defined` errors by adding missing imports in `admin/page.tsx` and `app/page.tsx`. +### [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. **Modified Files:** -- `frontend/app/admin/page.tsx` -- `frontend/app/page.tsx` +- `dev_docs/TECH_STACK.md` (New) +- `GEMINI.md` (Refined) +- `AI_RULES.md` (Cleaned) +- `PLAN.md` (Referenced tech stack) +- `requirements.md` (Referenced tech stack) +- `dev_docs/SESSION_STATE.md` (Path cleanup) - `VERSION.json` +### [2026-04-11 12:05] v1.2.6: Hotfix - Missing Icon Imports + ### [2026-04-11 11:58] v1.2.5: UI Icon Synchronization ### [2026-04-11 11:45] v1.2.4: Offline Auth & UX Polish diff --git a/dev_docs/SESSION_HISTORY.md b/dev_docs/SESSION_HISTORY.md index c650e7e1..b8c31c4e 100644 --- a/dev_docs/SESSION_HISTORY.md +++ b/dev_docs/SESSION_HISTORY.md @@ -5,6 +5,21 @@ Entries are added here when a new AI session starts. --- +**[Archived: 2026-04-11]** +**Status**: UI Readability Refactor Completed (v1.2.2). Ready for Phase 6. +**Current AI Agent**: Gemini (Antigravity) +**Context**: +- **UI Readability**: System-wide removal of `uppercase` and `tracking-*`. Font sizes increased from 9px/10px to xs/sm. Title Case applied to major buttons. +- **Rules Compliance**: All changes logged in `ARCHIVE_LOGS.md` and `VERSION.json`. +- **Git**: Working on branch `dev`. Path persisted in `.git_path`. + +**Next Steps**: +1. **Proceed to Phase 6: Audit Log Dashboard UI**. The backend already has `Log` models, but the frontend needs a more comprehensive view beyond the current "Audit History" modal if requested, OR finalize the existing ones. +2. Enable LDAP and test with real server (from v1.2.1 goals). +3. Deploy v1.2.2 to stable branch if user confirms. + +--- + ### Handover Archive (Auto-Archived) **Status**: v1.2.1 Infrastructure Stable. **Current AI Agent**: Gemini (Antigravity) diff --git a/dev_docs/SESSION_STATE.md b/dev_docs/SESSION_STATE.md index 7b94cccf..97e29a91 100644 --- a/dev_docs/SESSION_STATE.md +++ b/dev_docs/SESSION_STATE.md @@ -1,13 +1,15 @@ # AI Session State - HANDOVER -**Status**: UI Readability Refactor Completed (v1.2.2). Ready for Phase 6. +**Status**: v1.2.6 Hotfixed & UX Polished. Persistent Gemini Context Created. **Current AI Agent**: Gemini (Antigravity) **Context**: -- **UI Readability**: System-wide removal of `uppercase` and `tracking-*`. Font sizes increased from 9px/10px to xs/sm. Title Case applied to major buttons. -- **Rules Compliance**: All changes logged in `ARCHIVE_LOGS.md` and `VERSION.json`. -- **Git**: Working on branch `dev`. Path persisted in `.git_path`. +- **Offline Auth**: LDAP users now have local password hash caching (v1.2.4). +- **UI Affordance**: Added `ChevronDown` to selects and softened password dots. +- **Icon Sync**: Unified iconography (Layers = Categories, Package = Item Types). +- **Memory**: Created [GEMINI.md](../GEMINI.md) as the persistent entry point for this agent. +- **Version**: Currently at **v1.2.6**. Commit log in `ARCHIVE_LOGS.md`. **Next Steps**: -1. **Proceed to Phase 6: Audit Log Dashboard UI**. The backend already has `Log` models, but the frontend needs a more comprehensive view beyond the current "Audit History" modal if requested, OR finalize the existing ones. -2. Enable LDAP and test with real server (from v1.2.1 goals). -3. Deploy v1.2.2 to stable branch if user confirms. +1. **Phase 6: Advanced Audit Dashboard**. Current logs exist but could use a dedicated page with filtering. +2. Final testing of offline LDAP login (Basement simulation). +3. Verification of icon consistency in any new screens. diff --git a/dev_docs/TECH_STACK.md b/dev_docs/TECH_STACK.md new file mode 100644 index 00000000..39527796 --- /dev/null +++ b/dev_docs/TECH_STACK.md @@ -0,0 +1,25 @@ +# 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` diff --git a/requirements.md b/requirements.md index f1eacc61..a1ab88c2 100644 --- a/requirements.md +++ b/requirements.md @@ -6,16 +6,15 @@ A unified system to maintain an inventory of "items" and their quantities, inclu ## 2. Core Constraints & System Elements ### 2.1 Main Application Server (Linux Backend) -* **Target Environment:** Dockerized Linux Environment. -* **Framework:** Python (FastAPI) + SQLite database. -* **Users & Security:** Support multiple authenticated users (PBKDF2 local + optional LDAP). -* **Audit Compliance:** All operations maintain a strict audit log (unique UUIDs, details). +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) -* **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. +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.