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

docs: refactor documentation for portability and SSOT v1.2.7

Browse Source
This commit is contained in:
Daniel Bedeleanu
2026-04-11 11:57:13 +03:00
parent 96fe655f72
commit 432cd28ca5
9 changed files with 103 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
AI_RULES.md
View File

@@ -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 (`<i class="bi bi-something"></i>`); 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.

29
GEMINI.md Normal file
View File

@@ -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.).

15
PLAN.md
View File

@@ -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)

7
VERSION.json
View File

@@ -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)",

14
dev_docs/ARCHIVE_LOGS.md
View File

@@ -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

15
dev_docs/SESSION_HISTORY.md
View File

@@ -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)

16
dev_docs/SESSION_STATE.md
View File

@@ -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.

25
dev_docs/TECH_STACK.md Normal file
View File

@@ -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`

15
requirements.md
View File

@@ -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.