docs: consolidate all rules and specs into absolute sources of truth v1.2.8
This commit is contained in:
Daniel Bedeleanu
70
AI_RULES.md
70
AI_RULES.md
@@ -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.).
|
||||
Agent-specific instructions are located in `GEMINI.md` and `CLAUDE.md`.
|
||||
Any AI or session MUST respect these mandatory rules.
|
||||
**READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK.**
|
||||
This is the **Single Source of Truth** for ALL Artificial Intelligence agents (Claude, Gemini, etc.) working on this project.
|
||||
For technical architecture, data models, and stack details, refer to [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md).
|
||||
|
||||
## 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.
|
||||
|
||||
## Multi-AI Coordination & Handover
|
||||
## 1. Multi-AI Coordination & Memory
|
||||
- **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**.
|
||||
- **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.
|
||||
- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it according to `SESSION_STATE.md`.
|
||||
- **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**: 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.
|
||||
|
||||
## 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.
|
||||
- **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 BRANCHING STRUCTURE**:
|
||||
- The main stable branch is `master`.
|
||||
- All active development MUST occur in the `dev` branch.
|
||||
- Every major version MUST have its own dedicated archival branch named `vX` (e.g., `v1`, `v2`) which copies the state of the major release.
|
||||
- **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:
|
||||
## 2. Global Operational Laws
|
||||
- **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.
|
||||
- **COMMUNICATION LANGUAGE**: Conversation with the user will be in Romanian or English (preferably Romanian).
|
||||
- **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.
|
||||
- **COMMIT & PUSH STRICT RULE**:
|
||||
- Never push to remote (`git push`) or use force flags (`--hard`, `--force`) unless explicitly requested.
|
||||
- Always update `VERSION.json` on every commit.
|
||||
- Do NOT add AI co-author signatures (e.g., `Co-Authored-By: AI...`) to commit messages.
|
||||
- Branching: `master` (stable), `dev` (active development), `vX` (archival releases).
|
||||
- **MANDATORY LOGGING**: Document coding/architecture changes in `dev_docs/ARCHIVE_LOGS.md` at the end of the task.
|
||||
- **TRIPLE CONFIRMATION (Safe Forget)**: You cannot delete a physical location, item, or critical entity without explicit user permission three times.
|
||||
|
||||
## 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.
|
||||
```
|
||||
- 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 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.
|
||||
- Do not provide unnecessary verbatim summaries of the code.
|
||||
|
||||
29
GEMINI.md
29
GEMINI.md
@@ -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
43
PLAN.md
@@ -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).
|
||||
|
||||
## 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
|
||||
This document tracks the immediate implementation checklist. For overarching design and constraints, see [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md).
|
||||
|
||||
## Implementation Status
|
||||
- [x] **Phase 1: Backend Foundation** (FastAPI, SQLite, Models).
|
||||
- [x] **Phase 2: Modular AI Integration** (Gemini & Claude support, v2 SDK).
|
||||
- [x] **Phase 3: AI Onboarding UI** (Validation Mask, Camera/Upload integration).
|
||||
- [x] **Phase 2: Modular AI Integration** (Gemini support, v2 SDK).
|
||||
- [x] **Phase 3: AI Onboarding UI** (Validation Mask, Camera integration).
|
||||
- [x] **Phase 4: Offline Synchronization** (Deduplicated Dexie -> SQL sync logic).
|
||||
- [x] **Phase 5: Inventory Trash Management** (Waste/Discard/Damage workflow).
|
||||
- [ ] **Phase 6: Audit Log Dashboard UI** (Visual historical interventions).
|
||||
|
||||
## 5. Security & Infrastructure
|
||||
- **Unified SSL Proxy:** Integrated `local-ssl-proxy` for HTTPS access (Camera/Mic) on port 3003.
|
||||
- **VENV Isolation:** Automated `.venv` management in `start_server.sh`.
|
||||
*(Note: Completed phases are periodically moved to `dev_docs/PLAN_HISTORY.md` according to AI_RULES)*
|
||||
|
||||
54
PROJECT_ARCHITECTURE.md
Normal file
54
PROJECT_ARCHITECTURE.md
Normal 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
11
VERSION.json
@@ -1,8 +1,9 @@
|
||||
{
|
||||
"version": "1.2.7",
|
||||
"last_build": "2026-04-11-1216",
|
||||
"commit": "e8f7d",
|
||||
"version": "1.2.8",
|
||||
"last_build": "2026-04-11-1225",
|
||||
"commit": "ab3c9",
|
||||
"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.6: Hotfix - Added missing icon imports (Layers, ChevronDown)",
|
||||
"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.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.0: Structured category management with grouping support",
|
||||
"v1.1.0: Multi-user auth & LDAP framework integration",
|
||||
"v1.0.0: Initial PWA inventory launch"
|
||||
"v1.2.0: Structured category management with grouping support"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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
|
||||
**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:**
|
||||
|
||||
@@ -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*
|
||||
@@ -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`
|
||||
@@ -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)*
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user