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

docs: comprehensive cleanup and restructuring of project documentation

Browse Source
This commit is contained in:
Daniel Bedeleanu
2026-04-26 12:34:12 +03:00
parent b41a2dcf74
commit 2b42ec0d4d
19 changed files with 258 additions and 582 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
AI_MANDATES.md Normal file
View File

@@ -0,0 +1,44 @@
# AI AGENT MANDATES - SINGLE SOURCE OF TRUTH
**READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK.**
This is the foundational directive for all AI operations on the TFM aInventory project.
---
## 1. Memory, Traceability & Handover
- **Startup Protocol**: Read `dev_docs/SESSION_STATE.md` immediately at session start to understand the current context.
- **Handover Requirement**: Update `dev_docs/SESSION_STATE.md` at the end of every session with:
- **Active AI**: Your name/version.
- **Current Status**: Precise summary of what was achieved.
- **Context**: Any critical details found or technical decisions made.
- **Next Steps**: Explicit instructions for the next AI session.
- **Archive Protocol**: Before writing new state, move previous content to `dev_docs/SESSION_HISTORY.md`.
- **Communication**: Be concise. Focus on signal over noise.
## 2. Source Control & Versioning
- **Branch Strategy**: Work primarily in the `dev` branch. Feature branches are acceptable but must be merged back to `dev`.
- **Atomic Commits**: Each commit should represent a single logical change.
- **Version Bump**: You MUST run `python3 scripts/save_version.py` before finalizing any task that modifies code or functionality. This tool increments the version and updates `VERSION.json`.
## 3. Operational Guardrails
- **No Interaction Overlap**: Never modify a file if another AI session is explicitly working on it (check `dev_docs/SESSION_STATE.md`).
- **Standard Respect**: Rigorously follow `DESIGN_SYSTEM.md` and `CODING_STANDARDS.md`.
- **Conflict Resolution**: If project files contradict your internal training, **this file and local project docs take absolute precedence.**
- **Uppercase Rule**: NEVER use `uppercase` or `toUpper` in UI contexts. Leave text case as is or use Title/Sentence case.
## 4. Documentation SSOT Integrity
Every feature change or refactor MUST be reflected across the documentation suite:
1. `README.md` (Quick Start/Features)
2. `USER_GUIDE.md` (User workflows)
3. `ARCHITECTURE.md` (System logic)
4. `DESIGN_SYSTEM.md` (UI/UX specs)
5. `ROADMAP.md` (Project progress)
## 5. AI Command Shortcuts
- **`save-version`**:
- Update all relevant documentation.
- Run `python3 scripts/save_version.py`.
- Follow the script's automated prompts for commits and branching.
---
**Status**: ACTIVE | **Last Updated**: 2026-04-26

63
AI_RULES.md
View File

@@ -1,63 +0,0 @@
# AI AGENT RULES - MANDATORY SSOT ENTRY POINT
**READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK.**
This is the **Single Source of Truth** for ALL AI agents. Refer to [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md) for technical logic.
---
## 1. AI MEMORY, TRACEABILITY & HANDOVER
- **MANDATORY STARTUP**: Read `dev_docs/SESSION_STATE.md` immediately at session start.
- **PLAN RETIREMENT**: Mark a completed "Master Plan" as `[COMPLETED]` in the file itself. Move technical details to `dev_docs/ARCHIVE_LOGS.md` and `PLAN.md` entries to `dev_docs/PLAN_HISTORY.md`.
- **STRICT HANDOVER**: Update `dev_docs/SESSION_STATE.md` at the end of every task with: **Active AI**, **Current Status**, **Context**, and **Next Steps**.
- **SESSION ARCHIVE**: Move previous handover content to `dev_docs/SESSION_HISTORY.md` before writing new state.
- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it.
- **CONCISE COMMUNICATION**: Be concise! Do not explain a thousand details unless they are absolutely necessary.
## 2. ENGINEERING & OPERATIONAL LAWS
- **ENGLISH ONLY**: Interfaces, code, variables, and docs MUST be in English. Translate any Romanian text found in code immediately.
- **GIT PROTOCOL**: Use system `git`. Never push or use `--force` unless explicitly asked. Never push to master unless user say so. The maik work is done in "dev" git branch, and in other branches only user say so explicitly.
- **VERSIONING**: Update `VERSION.json` on every commit using `scripts/save_version.py`.
- **SSOT INTEGRITY**: Every feature change MUST update: `README.md`, `USER_GUIDE.md`, `PROJECT_ARCHITECTURE.md`, `DEPLOYMENT.md`, and `dev_docs/PLAN.md`.
- **CODE QUALITY**: Files under 300 lines, complexity < 10, strict Single Responsibility Principle.
## 3. UI/UX "PREMIUM" FIDELITY STANDARDS
- **Aesthetics**: Density must remain "Premium". Use Tailwind CSS. NO simplification.
- **Typography Rules**:
- **NO UPPERCASE** or **NO ITALICS** in any UI context (headers, labels, buttons).
- **NO BOLD FONTS**: Use `font-normal` throughout. Hierarchy via size and color only.
- **NO `tracking-widest`**.
- **StatCard Typography**: Numeric values in StatCards MUST match the exact text size of their corresponding labels (e.g., `text-base md:text-lg`) to avoid overwhelming the density of the component.
- **Shapes**: All components MUST use 0px border radius (sharp corners) and NO box-shadows. Depth via tonal layers and borders only.
- **Layout**: Main pages MUST use `max-w-7xl`.
- **Unified Headers**: Icon box (`p-4 bg-primary/10 border-primary/20`) + Title (`text-3xl font-normal`).
- **Iconography**: Use **Lucide Icons** exclusively.
## 4. REFACTORING & TESTING STRATEGY (MANDATORY)
- **TEST-FIRST**: All tests must be written and passing BEFORE refactoring any code.
- **ZERO REGRESSION**: 100% of existing tests must pass post-refactor.
- **GATING**:
- **Backend**: Pytest coverage target 85%+ (`backend/tests/`).
- **Frontend**: Vitest coverage target 80%+ (`frontend/tests/`).
- **E2E**: Critical workflows in Playwright (`frontend/e2e/`).
- **MODULARITY**: Break monolithic files into focused modules (<300 lines). Extract logic into hooks/services.
## 5. DATA INTEGRITY & SECURITY POLICY
- **RESTRICTED ACTIONS**: Destructive actions (DELETE) require Admin role.
- **AUDIT IMMUTABILITY**: Deleting an item MUST NOT delete its audit log.
- **NO AUTH BYPASS**: Authentication is NEVER disabled in any environment.
- **TRIPLE CONFIRMATION**: Deleting critical entities requires 3 confirmations.
- **NATIVE ALERTS**: Use `window.confirm` for destructive UI actions.
- **CREDENTIALS**: initialized via migrations/scripts. NEVER hardcoded or logged.
## 6. AI COMMAND SHORTCUTS
- **`save-version`**:
0. **MANDATORY**: Update ALL documentation with explanations of current changes.
1. Increment `VERSION.json`.
2. Git add/commit (`Build [vX.Y.Z]`).
3. Create snapshot branch.
4. Merge into `master`.
5. Run `./export_prod.sh`.
(Command: `python3 scripts/save_version.py`).
---
**Status**: ACTIVE

48
ARCHITECTURE.md Normal file
View File

@@ -0,0 +1,48 @@
# TFM aInventory - System Architecture
This document defines the technical architecture, business requirements, and core logic of the system. For engineering and design standards, refer to `CODING_STANDARDS.md` and `DESIGN_SYSTEM.md`.
---
## 1. Application Overview
A unified system for inventory management featuring web administration, offline-first field operations (PWA), and AI-powered data extraction from labels.
## 2. Tech Stack Summary
- **Backend**: FastAPI (Python 3.12+), SQLite (WAL mode).
- **Frontend**: Next.js 15+ (TypeScript), Dexie.js (IndexedDB).
- **AI**: Gemini 2.0 Flash (Primary), Claude 3.5 Sonnet (Fallback).
- **Operations**: Docker, Caddy (Reverse Proxy).
## 3. Core Business Logic
### 3.1 AI Extraction Pipeline
1. **Input**: Image capture or upload in the UI.
2. **Processing**: Backend receives image → calls Gemini/Claude with optimized prompts.
3. **Extraction**: Returns JSON: `name`, `part_number`, `quantity`, `category`, `specs`.
4. **Validation**: UI Wizard allows manual adjustment before finalizing.
### 3.2 Offline-First Sync Architecture
1. **Local Storage**: All writes are committed to IndexedDB (Dexie) immediately.
2. **Sync Mechanism**: Background worker identifies unsynced entries (UUID-based).
3. **Bulk Push**: Periodic attempts to push to `/sync/bulk` endpoint.
4. **Idempotency**: UUIDs prevent duplicate records on retry.
### 3.3 Audit Trail System
- Every modification creates an immutable `LogEntry`.
- Audit logs are decoupled from item deletion; history is preserved even if the item is removed.
## 4. Configuration Architecture
The system uses domain-specific YAML files located in `config/`:
- `network.yaml`: SSOT for hostnames, ports, and CORS origins.
- `secrets.yaml`: JWT keys, API keys (never committed).
- `backend.yaml`: Database and performance tuning.
## 5. Security Architecture
- **Authentication**: Hybrid LDAP + Local fallback.
- **Authorization**: Role-based access (Admin for destructive actions).
- **Encryption**: JWT for stateless sessions, PBKDF2 for password hashing.
- **CORS**: Enforced via `config/network.yaml`.
---
**Last Updated**: 2026-04-26
**Version**: 1.15.0

78
CLAUDE.md
View File

@@ -4,70 +4,26 @@ You are Claude, operating on the TFM aInventory project.
**IMMEDIATE MANDATORY ACTION:** **IMMEDIATE MANDATORY ACTION:**
Before taking any action or writing code, you MUST read the following Single Source of Truth files: Before taking any action or writing code, you MUST read the following Single Source of Truth files:
1. `AI_RULES.md` (Contains your operational constraints, Git rules, and UI fidelity laws). 1. `AI_MANDATES.md` (Operational constraints, Git rules, Handover protocols).
2. `PROJECT_ARCHITECTURE.md` (Contains the tech stack, data models, and system logic). 2. `DESIGN_SYSTEM.md` (UI/UX standards, Colors, Typography).
3. `dev_docs/SESSION_STATE.md` (Contains the current handover status from the previous AI). 3. `CODING_STANDARDS.md` (Engineering rules, Testing, Security).
4. `DESIGN_COLOR_RULES.md` (MANDATORY for ALL UI/UX work - No hardcoded Tailwind colors allowed). 4. `ARCHITECTURE.md` (System logic, Data models, Offline sync).
5. `dev_docs/SESSION_STATE.md` (Current handover status).
**STRICT COMMUNICATION RULE:** **STRICT COMMUNICATION RULE:**
Be concise! Do not explain a thousand details unless they are absolutely necessary. Be concise! Focus on signal over noise.
Do not proceed with any task until you have analyzed these three files. ---
DO NOT, EVER, USE "uppercase" or "toUpper" in any UI/UX context, nowhere. This SHOULD NOT be used in UI/UX anywhere, no text should be displayed in CAPITAL LETTERS! But do not replace "toUpper" with "toLower" or "uppercase" with "lowercase" either, leave text in UI/UX as is. ## 🎨 CRITICAL DESIGN RULE
**NO HARDCODED TAILWIND COLORS.**
- All colors MUST come from `DESIGN_SYSTEM.md` (via `colors.mjs`).
- **NO BOLD FONTS.** Hierarchy via size and color only.
- **NO UPPERCASE.** Use Title/Sentence case.
## 🎨 CRITICAL COLOR RULE FOR ALL UI/UX WORK ## 🔒 COLOR SSOT
All color changes MUST be made in `frontend/colors.mjs` ONLY.
Run `npm run build` to sync CSS variables and Tailwind config.
**NO HARDCODED TAILWIND COLORS ALLOWED** ❌ ---
- ❌ Never use `bg-green-500`, `text-red-600`, `border-blue-400`, etc. **Status**: ACTIVE
- ✅ Always use semantic colors from DESIGN.md: `bg-primary`, `text-tertiary`, `bg-error`
- 📖 **MANDATORY READ:** `DESIGN_COLOR_RULES.md` before ANY frontend code
**Semantic Color Mapping:**
- ✅ Success/Healthy: `tertiary` (#00e639)
- ❌ Error/Destructive: `error` (#ffb4ab)
- ⚠️ Warning/Caution: `primary` (#ffb781)
- ℹ️ Info/Secondary: `secondary` (#c8c6c5)
See `DESIGN_COLOR_RULES.md` for complete color mapping and examples.
## 🔒 MANDATORY: All Color Changes → `frontend/colors.mjs` ONLY
**SINGLE SOURCE OF TRUTH RULE:**
When implementing any color changes from DESIGN.md (new colors, updates, or variants):
1. **Edit ONLY:** `frontend/colors.mjs` (the authoritative source)
2. **DO NOT edit:** `tailwind.config.ts` (auto-imports from colors.mjs)
3. **DO NOT edit:** `frontend/app/globals.css` (auto-generated from colors.mjs)
4. **Run:** `npm run build` (auto-syncs all systems)
**Why:**
- Single source of truth eliminates duplication
- Build script auto-generates CSS variables
- No manual sync needed
- Zero risk of color inconsistency
**Violation Examples (DO NOT DO):**
- ❌ Editing hex values in `tailwind.config.ts` directly
- ❌ Adding CSS variables to `globals.css` manually
- ❌ Updating colors in multiple files
**Correct Workflow:**
```javascript
// ✅ CORRECT: Update colors.mjs ONLY
// frontend/colors.mjs
export const colors = {
primary: {
DEFAULT: "#ffb781", // ← Update here
},
};
// Then: npm run build (everything auto-syncs)
```
**Reference:** See `COLOR_SYSTEM_ARCHITECTURE.md` for implementation details.
## Project-Specific Guidelines
- Use TypeScript strict mode
- All API endpoints must have tests
- All UI colors MUST follow DESIGN.md (see DESIGN_COLOR_RULES.md)

44
CODING_STANDARDS.md Normal file
View File

@@ -0,0 +1,44 @@
# TFM aInventory - Coding Standards
**Status**: ACTIVE | **Last Updated**: 2026-04-26
---
## 1. General Principles
- **Language**: All code, variables, and documentation MUST be in **English**.
- **Modularity**: Files should be under **300 lines**. Extract logic into hooks (frontend) or services (backend).
- **Simplicity**: Strict Single Responsibility Principle (SRP). Complexity score < 10.
## 2. Backend (FastAPI / Python)
- **Framework**: FastAPI (Async/Await)
- **Validation**: Pydantic v2
- **Database**: SQLAlchemy 2.0 (Async) + Alembic migrations.
- **Testing**: Pytest. **Target Coverage: 85%+**.
- **Naming**: `snake_case` for variables/functions, `PascalCase` for classes.
## 3. Frontend (Next.js / TypeScript)
- **Framework**: Next.js 15+ (App Router, Strict TypeScript).
- **Styling**: Tailwind CSS (refer to `DESIGN_SYSTEM.md`).
- **State Management**: React Hooks + Dexie.js (Offline IndexDB).
- **Testing**: Vitest for unit, Playwright for E2E. **Target Coverage: 80%+**.
- **Naming**: `camelCase` for variables/functions, `PascalCase` for components.
## 4. Testing Strategy (MANDATORY)
- **Test-First**: Write and pass tests BEFORE refactoring or adding features.
- **Zero Regression**: 100% of existing tests must pass post-change.
- **Gating**:
- Backend: `pytest backend/tests/`
- Frontend: `npm run test`
- E2E: `npx playwright test`
## 5. Security & Data Integrity
- **Restricted Actions**: DELETE requires Admin role.
- **Audit Immortality**: Deleting an item MUST NOT delete its `AuditLog` history.
- **Authentication**: Never bypassed, even in development. PBKDF2 for local, LDAP for enterprise.
- **Credentials**: Use `.env` or YAML config. NEVER hardcode or log secrets.
- **Confirmations**: Destructive actions require triple confirmation or native `window.confirm`.
## 6. Versioning & Workflow
- **Git**: Use `dev` branch for active work. Never push to `master` directly.
- **Versioning**: Run `python3 scripts/save_version.py` on every commit.
- **Documentation**: Every feature change MUST update: `README.md`, `USER_GUIDE.md`, `ARCHITECTURE.md`, `DEPLOYMENT.md`, and `ROADMAP.md`.

65
DESIGN_SYSTEM.md Normal file
View File

@@ -0,0 +1,65 @@
# TFM aInventory - Design System
**Status**: ACTIVE | **Last Updated**: 2026-04-26
**Target**: Premium Industrial Fidelity (Sharp, Dense, High-Contrast)
---
## 1. Core Visual Principles
- **Aesthetics**: "Premium Industrial". Density must remain high.
- **Shapes**: **STRICT 0px border radius** (sharp corners) on all components.
- **Depth**: No box-shadows. Use tonal layers, borders (1px/2px), and contrast for depth.
- **Layout**: Main page containers MUST use `max-w-7xl`.
## 2. Typography Rules (MANDATORY)
Hierarchy is achieved ONLY via size and color.
- **NO BOLD FONTS**: Use `font-normal` (400) throughout the entire application.
- **NO UPPERCASE**: All text must be Title Case or Sentence Case. NEVER use `uppercase` or `toUpper`.
- **NO ITALICS**: Italics are forbidden.
- **Letter Spacing**:
- `headline-lg`: -0.02em
- `headline-md/sm`: -0.01em
- `label-md`: +0.05em
- **StatCard Rule**: Numeric values MUST match the exact text size of their corresponding labels (e.g., `text-base md:text-lg`).
## 3. Color System (Single Source of Truth)
All colors are defined in `frontend/colors.mjs`. **Hardcoded Tailwind colors (e.g., bg-blue-500) are FORBIDDEN.**
### Semantic Mapping
| Intent | Color | Value | Use Case |
|--------|-------|-------|----------|
| **Primary / Caution** | `primary` | #ffb781 | Primary actions, "Caution Orange", important warnings |
| **Secondary / Info** | `secondary` | #c8c6c5 | Secondary actions, hints, metadata |
| **Success / Healthy** | `tertiary` | #00e639 | Success status, "Scanner Ready", stock added |
| **Error / Destructive** | `error` | #ffb4ab | Errors, "Delete", low stock, offline |
| **Muted** | `muted` | #474746 | Disabled states, placeholders |
### Surface Tiers
- **Background**: #131313 (`bg-background`)
- **Surface**: #1c1b1b (`bg-surface`)
- **Outline**: #a48c7c (`border-outline`)
- **Outline Variant**: #564335 (`border-outline-variant`)
## 4. Spacing & Grid
Base unit: **4px**.
- **Gutter**: 16px (`gap-4`)
- **Margin**: 32px (`p-8` / `m-8`)
- **Stack-SM**: 8px (`space-y-2`)
- **Stack-MD**: 16px (`space-y-4`)
## 5. Components & Icons
- **Iconography**: Use **Lucide Icons** exclusively. Size: 20px (default), 16px (compact).
- **Unified Headers**: Icon box (`p-4 bg-primary/10 border-primary/20`) + Title (`text-3xl font-normal`).
- **Buttons**:
- Primary: `bg-primary text-on-primary`
- Secondary: `bg-secondary text-on-secondary`
- Destructive: `bg-error text-on-error`
- All: `hover:opacity-80 transition-all active:scale-95`
## 6. Z-Index Scale
- `z-10`: Local stacking (hover states)
- `z-20`: Cards, modals (low)
- `z-30`: Dropdowns, tooltips
- `z-40`: Fixed navigation (BottomNav)
- `z-50`: Full-screen overlays (Scanner, AIOnboarding)
- `z-[100]`: Toasts, critical alerts

23
GEMINI.md
View File

@@ -4,23 +4,22 @@ You are Gemini (Antigravity), operating on the TFM aInventory project.
**IMMEDIATE MANDATORY ACTION:** **IMMEDIATE MANDATORY ACTION:**
Before taking any action or writing code, you MUST read the following Single Source of Truth files: Before taking any action or writing code, you MUST read the following Single Source of Truth files:
1. `AI_RULES.md` (Contains your operational constraints, Git rules, and UI fidelity laws). 1. `AI_MANDATES.md` (Operational constraints, Git rules, Handover protocols).
2. `PROJECT_ARCHITECTURE.md` (Contains the tech stack, data models, and system logic). 2. `DESIGN_SYSTEM.md` (UI/UX standards, Colors, Typography).
3. `dev_docs/SESSION_STATE.md` (Contains the current handover status from the previous AI). 3. `CODING_STANDARDS.md` (Engineering rules, Testing, Security).
4. `ARCHITECTURE.md` (System logic, Data models, Offline sync).
5. `dev_docs/SESSION_STATE.md` (Current handover status).
**STRICT COMMUNICATION RULE:** **STRICT COMMUNICATION RULE:**
Be concise! Do not explain a thousand details unless they are absolutely necessary. Be concise! Focus on signal over noise.
Do not proceed with any task until you have analyzed these three files. ---
DO NOT, EVER, USE "uppercase" or "toUpper" in any UI/UX context, nowhere. This SHOULD NOT be used in UI/UX anywhere, no text should be displayed in CAPITAL LETTERS! But do not replace "toUpper" with "toLower" or "uppercase" with "lowercase" either, leave text in UI/UX as is.
## graphify ## graphify
This project has a graphify knowledge graph at graphify-out/. This project has a graphify knowledge graph at graphify-out/.
- Use `graphify query`, `graphify path`, or `graphify explain` for architectural insights.
- Run `graphify update .` after significant code changes.
Rules: ---
- Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure **Status**: ACTIVE
- If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

322
PLAN.md
View File

@@ -1,322 +0,0 @@
# DESIGN.md Compliance Audit & Fix Plan
**Status**: PLAN READY FOR REVIEW (No code changes made yet)
**Date**: 2026-04-25
**Objective**: Audit why DESIGN.md is not fully respected in UI/UX and plan comprehensive fixes
---
## EXECUTIVE SUMMARY
The design system has **partial implementation**. While basic structure exists (sharp corners, no shadows, dark theme), critical issues prevent full DESIGN.md compliance:
1. **Color system is incomplete** — tailwind.config.ts missing 50%+ of DESIGN.md colors
2. **Hardcoded tailwind classes** bypass the design system (bg-slate-*, focus:ring-blue-*)
3. **Global CSS variables** only cover 5 colors instead of full palette
4. **Spacing tokens missing** (stack-sm, stack-md, container-gap)
5. **Typography spacing** incomplete (letter-spacing, line-height rules)
---
## ROOT CAUSE ANALYSIS
### Why DESIGN.md Is Not Being Respected
#### 1. **Incomplete Color Mapping** (PRIMARY ISSUE)
**DESIGN.md Specifies:**
- Primary: `#ffb781` (warm orange)
- Secondary: `#c8c6c5` (light gray for contrast)
- Tertiary: `#00e639` (terminal green for "healthy" status)
- Error: `#ffb4ab` + container `#93000a`
- On-surface: `#e5e2e1` (text on dark surfaces)
- On-primary: `#4e2600`
- On-secondary: `#303030`
- Outline: `#a48c7c`, Outline-variant: `#564335`
- Surface variants: 5 tiers (#0e0e0e to #353534)
**Current tailwind.config.ts Has:**
```
primary: #F58618 ❌ WRONG (should be #ffb781)
secondary: #888888 ❌ WRONG (should be #c8c6c5)
success: #00FF41 ❌ WRONG (should be #00e639)
tertiary: MISSING ENTIRELY ❌
error: #FF3131 ❌ WRONG (should be #ffb4ab)
on-surface: MISSING ❌
on-primary: MISSING ❌
outline: MISSING ❌
```
**Impact**: Components using `text-secondary` get `#888888` instead of `#c8c6c5`. Buttons and status indicators use wrong colors.
---
#### 2. **Hardcoded Tailwind Classes Bypass Design System**
**Found in Components:**
- `bg-slate-400`, `bg-slate-600`, `hover:bg-slate-600` — No such colors in design
- `bg-gray-400`, `text-gray-300`, `text-gray-400` — Undefined colors
- `focus:ring-blue-500` — Should use primary color system
- `hover:bg-[#222222]` — Hardcoded hex instead of tonal layer name
**Examples from audit:**
```tsx
// ItemPhotoUpload.tsx
className="hover:bg-slate-600" // ❌ Undefined in design
// ItemComparisonModal.tsx
focus:ring-2 focus:ring-blue-500 // ❌ Should be focus:ring-primary
// DebugRotationPanel.tsx
hover:bg-slate-600 // ❌ Multiple instances
```
**Impact**: Colors change without design system knowledge. No way to enforce consistency.
---
#### 3. **Global CSS Variables Only Partially Implemented**
**Currently Defined:**
```css
--background: #0A0A0A
--foreground: #FFFFFF
--primary: #F58618
--border: #222222
--muted: #888888
```
**Missing 30+ Design System Variables:**
- All on-surface, on-primary, on-secondary variants
- All surface container levels (surface-container-lowest, surface-container-high, etc.)
- Outline and outline-variant
- Tertiary color suite
- Error container colors
- All inverse color variants
- Semantic spacing tokens
**Impact**: Can't reference design colors via CSS variables. Forces hardcoded hex values.
---
#### 4. **Spacing Tokens Missing from Config**
**DESIGN.md Specifies:**
```yaml
spacing:
unit: 4px
gutter: 16px
margin: 32px
container-gap: 24px
stack-sm: 8px
stack-md: 16px
```
**Current tailwind.config.ts**: Uses default Tailwind spacing (no custom tokens)
**Impact**: Margins and padding inconsistent across pages. No semantic spacing vocabulary.
---
#### 5. **Typography Rules Partially Implemented**
**DESIGN.md Specifies Letter-Spacing:**
- headline-lg: `-0.02em`
- headline-md: `-0.01em`
- body-md/lg: default (0)
- label-md: `+0.05em`
**Current globals.css:**
```css
h1, h2, h3, h4, h5, h6 { @apply tracking-tighter; }
```
Only `tracking-tighter` applied to all headings. No distinction between sizes.
**Impact**: Typography doesn't match spec. Density and legibility inconsistent.
---
## WHERE CHANGES ARE NEEDED
### 1. **frontend/tailwind.config.ts** (CRITICAL - 80+ lines)
**Changes Required:**
- Replace `colors.primary` with exact DESIGN.md hex values
- Add complete DESIGN.md color palette (50+ colors)
- Add missing typography scale entries
- Add spacing tokens (`unit`, `gutter`, `margin`, `stack-*`, `container-gap`)
- Add all color variants (`on-surface`, `on-primary`, etc.)
**Files to Edit:** `frontend/tailwind.config.ts`
---
### 2. **frontend/app/globals.css** (HIGH PRIORITY - 50+ lines)
**Changes Required:**
- Add CSS variables for ALL DESIGN.md colors (from :root)
- Add CSS variables for spacing tokens
- Update typography layer rules (different tracking per size)
- Add semantic classes for DESIGN.md color naming (`.on-surface`, `.on-primary`, etc.)
- Override default Tailwind focus ring color
**Files to Edit:** `frontend/app/globals.css`
---
### 3. **Component Files** (HIGH VOLUME - 30+ files)
**Search and Replace Pattern:**
```
bg-slate-* → bg-surface-bright or specific design color
bg-gray-* → bg-muted or specific design color
focus:ring-blue-500 → focus:ring-primary
hover:bg-slate-600 → hover:bg-surface-bright or level-2
text-gray-* → text-secondary or text-muted
bg-[#222222] → bg-border (when for borders)
```
**Files to Review:**
- `frontend/components/ItemPhotoUpload.tsx`
- `frontend/components/DebugRotationPanel.tsx`
- `frontend/components/ImageAdjustmentModal.tsx`
- `frontend/components/ManualCropUI.tsx`
- `frontend/components/ItemComparisonModal.tsx`
- `frontend/components/CategoryCreationModal.tsx`
- `frontend/components/CreateUserModal.tsx`
- All other components with hardcoded colors
---
## DETAILED FIX PLAN
### Phase 1: Color System Foundation
**Step 1.1 - Update tailwind.config.ts**
- Add complete DESIGN.md color palette as semantic color names
- Map all 40+ colors from DESIGN.md
- Ensure primary, secondary, tertiary, error, and all "on-" variants exist
- Add surface container levels
**Step 1.2 - Update globals.css**
- Add CSS variable definitions for all colors
- Create semantic class names for typography (`.headline-lg`, `.body-md`, etc.)
- Add proper tracking/letter-spacing rules per DESIGN.md spec
- Override Tailwind focus ring defaults to use primary color
**Step 1.3 - Verify Color Consistency**
- All hex values match DESIGN.md exactly
- No hardcoded colors remain in globals.css
- All semantic names follow Material Design naming convention
---
### Phase 2: Spacing System
**Step 2.1 - Add Spacing Tokens**
- Add `unit: 4px` as base spacing
- Add `gutter: 16px`, `margin: 32px`, `container-gap: 24px`
- Add `stack-sm: 8px`, `stack-md: 16px`
- Update tailwind spacing scale to reference these
**Step 2.2 - Component Spacing Audit**
- Verify all page margins use `m-[32px]` or semantic class
- Verify internal padding respects 4px grid
- Verify gaps between items use stack tokens
---
### Phase 3: Typography System
**Step 3.1 - Implement Typography Scale**
- Add custom Tailwind class for each typography level
- Implement correct letter-spacing per DESIGN.md (headline-lg: `-0.02em`, etc.)
- Add line-height rules (1.1 for headlines, 1.5 for body)
**Step 3.2 - Font Weight Enforcement**
- Ensure no font-weight values other than 400 in CSS
- Verify global `font-weight: 400 !important` is enforced
- Check that hierarchy comes ONLY from size + color
---
### Phase 4: Component Compliance
**Step 4.1 - Search and Replace**
Replace all hardcoded Tailwind colors:
| Current | Replace With | Reason |
|---------|--------------|--------|
| `bg-slate-*` | `bg-surface-bright` or design color | Undefined in system |
| `bg-gray-*` | `bg-muted` or `bg-secondary` | Undefined in system |
| `focus:ring-blue-500` | `focus:ring-primary` | Wrong color system |
| `hover:bg-slate-600` | `hover:bg-surface-bright` or level-2 | Undefined in system |
| `text-gray-*` | `text-secondary` or `text-muted` | Undefined in system |
| `bg-[#222222]` (for hover) | `hover:bg-border` or `hover:bg-surface-bright` | Use design token |
**Step 4.2 - Focus State Audit**
- All `:focus` and `:focus-visible` should use primary color
- Verify ring width (2px) matches design spec
- Remove any blue-500 references
**Step 4.3 - Border Audit**
- All borders should use `border-border` or `border-primary`
- No hardcoded `#222222` in border definitions
- Verify 1px vs 2px matches DESIGN.md spec
---
## FILES REQUIRING CHANGES
### Critical (Must Fix)
1. **frontend/tailwind.config.ts** — Add 50+ colors + spacing
2. **frontend/app/globals.css** — Add 50+ CSS variables + typography rules
### High Priority (30+ files with hardcoded colors)
3. `frontend/components/ItemPhotoUpload.tsx`
4. `frontend/components/DebugRotationPanel.tsx`
5. `frontend/components/ImageAdjustmentModal.tsx`
6. `frontend/components/ManualCropUI.tsx`
7. `frontend/components/ItemComparisonModal.tsx`
8. `frontend/components/CategoryCreationModal.tsx`
9. `frontend/components/CreateUserModal.tsx`
10. All other `/components/*.tsx` files with `bg-slate-`, `bg-gray-`, `focus:ring-blue-`
### Medium Priority
- `frontend/app/items/create.tsx` (has `bg-slate-400`)
- `frontend/app/inventory/page.tsx`
- `frontend/app/admin/page.tsx`
---
## EXPECTED OUTCOMES
After implementation:
✅ All DESIGN.md colors mapped 1:1 to tailwind.config.ts
✅ All 40+ CSS variables available in globals.css
✅ Zero hardcoded Tailwind colors (bg-slate-*, bg-gray-*, focus:ring-blue-*)
✅ All components use semantic color names (primary, secondary, surface-bright, etc.)
✅ Spacing tokens enable consistent, grid-aligned layout
✅ Typography follows DESIGN.md letter-spacing rules exactly
✅ Focus states use primary color consistently
✅ 100% compliance with DESIGN.md specification
---
## VERIFICATION CHECKLIST
- [ ] tailwind.config.ts has all 40+ DESIGN.md colors
- [ ] globals.css has CSS variables for all colors
- [ ] No `bg-slate-*` or `bg-gray-*` in any component
- [ ] No `focus:ring-blue-*` anywhere in codebase
- [ ] All typography uses proper letter-spacing per DESIGN.md
- [ ] Spacing tokens defined and used in config
- [ ] Primary color changed from `#F58618` to `#ffb781` (if this is correct)
- [ ] All component audits passed
- [ ] Visual inspection: colors match DESIGN.md visual palette
---
**NEXT STEP**: User reviews this plan and approves before code changes begin.

82
PROJECT_ARCHITECTURE.md
View File

@@ -1,82 +0,0 @@
# 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 for inventory management featuring web administration, offline field operations (PWA), audit logging, and AI-powered label extraction.
## 2. Technical Stack
### 2.1 Backend (API & Data)
- **Language**: Python 3.12+
- **Framework**: FastAPI (Async ASGI)
- **Database**: SQLite (SQLAlchemy) with WAL mode for concurrency
- **Validation**: Pydantic v2
- **Auth**: Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching
- **AI Engine**: Google GenAI (Gemini 2.0 Flash) & Anthropic (Claude 3.5 Sonnet)
- **Logging**: Python `logging` with rotation (10MB per file)
### 2.2 Frontend (Web & PWA)
- **Architecture**: Next.js 15+ (App Router, TypeScript Strict)
- **Styling**: Tailwind CSS v3.4 (Industrial Precision, Space Grotesk, normal weight only)
- **Icons**: Lucide Icons (exclusive)
- **Offline Persistence**: Dexie.js (IndexedDB)
- **Scanner**: `html5-qrcode` (Client-side, offline)
- **Sync**: Axios with UUID-based idempotency
### 2.3 Operations & Tooling
- **PWA**: `next-pwa` (Service Workers + Manifest)
- **HTTPS Proxy**: Caddy (Ports 8918/8919)
- **Containerization**: Docker & Docker Compose
- **Deployment**: `deploy.py` (Docker) or `run_standalone.py` (Standalone)
- **Configuration**: Domain-specific YAML (`config/`) with `network.yaml` as SSOT.
---
## 3. Core Business Logic
### 3.1 AI Extraction Pipeline
1. Capture/Upload image in UI.
2. Send to Backend → Process via Gemini (Primary) or Claude (Fallback).
3. Extract JSON: `name`, `part_number`, `quantity`, `category`, `specs`.
4. Validate extraction in UI wizard before saving.
### 3.2 Offline-First Sync
1. All changes saved locally to IndexedDB immediately.
2. Background sync attempts to push to Backend via `/sync/bulk` endpoint.
3. UUIDs ensure idempotency (no duplicate items on retry).
### 3.3 Audit Trail
- Every modification creates a `LogEntry`.
- Logs are immutable and stored in a separate table.
- Deleting an `Item` preserves its `AuditLog` history.
---
## 4. Design & Mobile Constraints
### 4.1 Spacing & Layout
- **Container**: `max-w-7xl` for main pages.
- **Responsive Spacing**: `space-y-3` (mobile) → `space-y-6` (desktop).
- **Padding**: `p-4` (mobile) → `p-8` (desktop).
- **Height**: Avoid `min-h-screen` on mobile to prevent viewport overflow; use `md:min-h-screen`.
### 4.2 Typography
- **Readability**: Standard camel/Title case.
- **NO UPPERCASE**: Strictly forbidden in UI text.
- **NO BOLD**: Use `font-normal`. Hierarchy via size (`text-sm` vs `text-3xl`) and color (`text-slate-500` vs `text-white`).
---
## 5. Security Architecture
- **JWT**: Stateless tokens for API auth.
- **LDAP**: Primary source of truth for users in enterprise mode.
- **Password Caching**: Encrypted local cache for offline authentication.
- **CORS**: Restricted origins in production via `config/network.yaml` (SSOT).
---
**Last Updated**: 2026-04-25
**Version**: 1.14.30

67
README.md
View File

@@ -1,60 +1,51 @@
# TFM aInventory (2026 Edition) # TFM aInventory (2026)
A unified, offline-first Inventory Management System built as a Progressive Web App (PWA). Features include AI-powered label extraction (OCR), local barcode/QR scanning, and multi-user authentication with LDAP support. A unified, offline-first Inventory Management System built as a Progressive Web App (PWA).
**Premium Industrial Fidelity | AI-Powered Extraction | Enterprise Sync**
---
## 📖 Project Documentation
### For End-Users
- **[USER_GUIDE.md](USER_GUIDE.md)**: Manual for field operators and inventory managers.
### For Developers & AI Agents
- **[AI_MANDATES.md](AI_MANDATES.md)**: **CRITICAL** operational rules for AI agents.
- **[DESIGN_SYSTEM.md](DESIGN_SYSTEM.md)**: UI/UX standards, colors, and typography.
- **[CODING_STANDARDS.md](CODING_STANDARDS.md)**: Programming rules, testing targets, and security.
- **[ARCHITECTURE.md](ARCHITECTURE.md)**: Technical logic, sync patterns, and tech stack.
- **[DEPLOYMENT.md](DEPLOYMENT.md)**: Server setup, Docker, and environment configuration.
- **[ROADMAP.md](ROADMAP.md)**: Project history and active planning.
--- ---
## 🚀 Quick Start (Production) ## 🚀 Quick Start (Production)
For production environments, Docker is the recommended deployment method:
```bash ```bash
git clone <repository-url> tfm-inventory git clone <repository-url> tfm-inventory
cd tfm-inventory cd tfm-inventory
# [D-08] Configuration - Copy examples to actual config files # Configuration
for f in config/*.yaml.example; do cp "$f" "${f%.example}"; done for f in config/*.yaml.example; do cp "$f" "${f%.example}"; done
# Edit config/secrets.yaml with your keys
# Edit config/secrets.yaml with your JWT_SECRET_KEY and AI keys
nano config/secrets.yaml nano config/secrets.yaml
# Deploy using the new Python deployment script # Deploy
python3 scripts/deploy.py production python3 scripts/deploy.py production
``` ```
- **Frontend**: http://localhost:3000 (or https://localhost:8919 via proxy) - **Frontend**: http://localhost:3000
- **Backend API**: http://localhost:8000/docs - **Backend API**: http://localhost:8000/docs
For detailed configuration reference, see **[config/README.md](config/README.md)**.
For detailed deployment instructions (Docker vs Standalone), see **[DEPLOYMENT.md](DEPLOYMENT.md)**.
--- ---
## 🏗 Technical Overview ## 🏗 Key Features
* **Backend:** FastAPI (Python 3.12+) - **Offline-First**: Continuous operation without network; background sync via IndexedDB.
* **Frontend:** Next.js 15+ (React PWA) with responsive Tailwind CSS - **AI OCR**: Intelligent label extraction using Gemini & Claude.
* **Database:** SQLite (SQLAlchemy) with Dexie.js (IndexedDB) for client-side sync. - **Enterprise Ready**: LDAP authentication, immutable audit logs, and SQLite WAL mode.
* **AI Engine:** Google Gemini (Primary) & Anthropic Claude (Fallback). - **PWA**: Installable on any mobile device.
* **Configuration:** [D-07] Consolidated YAML-based config in `config/` directory.
For more details on system logic, see **[PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md)**.
--- ---
**Current Version**: 1.15.0
## 🔐 Security & Constraints **Status**: Active Development
AI agents and developers MUST strictly follow the rules defined in **[AI_RULES.md](AI_RULES.md)**.
- **No Uppercase UI**: All labels/headers must be normal case.
- **No Bold Fonts**: Text hierarchy is achieved through size and color.
- **Offline-First**: All features must function without an active network connection.
---
## 📦 Production Distribution
To generate a clean production package:
`python3 scripts/save_version.py --patch` (or `--minor`/`--major`)
---
**Last Updated**: 2026-04-25
**Version**: 1.14.25 (Phase 7.1)

4
dev_docs/PLAN.md → ROADMAP.md
View File

@@ -49,10 +49,6 @@ A unified inventory management system that eliminates manual data entry through
## 5. Design & Operational Constraints ## 5. Design & Operational Constraints
- **Tech Stack**: FastAPI (Python), SQLite, Next.js (TypeScript), Tailwind CSS. - **Tech Stack**: FastAPI (Python), SQLite, Next.js (TypeScript), Tailwind CSS.
<<<<<<< HEAD
- **UI Fidelity**: Premium density, Lucide icons, **NO UPPERCASE**, **NO BOLD FONTS**.
- **Security**: Mandatory auth, immutable audit logs.
=======
- **UI Fidelity**: Premium density, Lucide icons, **NO UPPERCASE**, **NO BOLD FONTS** (normal weight only). - **UI Fidelity**: Premium density, Lucide icons, **NO UPPERCASE**, **NO BOLD FONTS** (normal weight only).
- **StatCard Rule**: Numeric values MUST match label text size for balanced density. - **StatCard Rule**: Numeric values MUST match label text size for balanced density.
- **Database**: Single-instance SQLite (WAL mode). Multi-instance is v3+. - **Database**: Single-instance SQLite (WAL mode). Multi-instance is v3+.

0
7-UI-REVIEW.md → dev_docs/archive/7-UI-REVIEW.md
View File

0
dev_docs/ARCHIVE_LOGS.md → dev_docs/archive/ARCHIVE_LOGS.md
View File

0
COLOR_SYSTEM_ARCHITECTURE.md → dev_docs/archive/COLOR_SYSTEM_ARCHITECTURE.md
View File

0
DESIGN-TYPOGRAPHY-HIERARCHY.md → dev_docs/archive/DESIGN-TYPOGRAPHY-HIERARCHY.md
View File

0
DESIGN.md → dev_docs/archive/DESIGN_AUDIT_2026-04-25.md
View File

0
DESIGN_COLOR_RULES.md → dev_docs/archive/DESIGN_COLOR_RULES.md
View File

0
dev_docs/DESIGN_COMPLIANCE_FIX_PLAN.md → dev_docs/archive/DESIGN_COMPLIANCE_FIX_PLAN.md
View File

0
dev_docs/PHASE_9_SUMMARY.md → dev_docs/archive/PHASE_9_SUMMARY.md
View File