docs: comprehensive cleanup and restructuring of project documentation
This commit is contained in:
44
AI_MANDATES.md
Normal file
44
AI_MANDATES.md
Normal 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
63
AI_RULES.md
@@ -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
48
ARCHITECTURE.md
Normal 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
78
CLAUDE.md
@@ -4,70 +4,26 @@ You are Claude, operating on the TFM aInventory project.
|
||||
|
||||
**IMMEDIATE MANDATORY ACTION:**
|
||||
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).
|
||||
2. `PROJECT_ARCHITECTURE.md` (Contains the tech stack, data models, and system logic).
|
||||
3. `dev_docs/SESSION_STATE.md` (Contains the current handover status from the previous AI).
|
||||
4. `DESIGN_COLOR_RULES.md` (MANDATORY for ALL UI/UX work - No hardcoded Tailwind colors allowed).
|
||||
1. `AI_MANDATES.md` (Operational constraints, Git rules, Handover protocols).
|
||||
2. `DESIGN_SYSTEM.md` (UI/UX standards, Colors, Typography).
|
||||
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:**
|
||||
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.
|
||||
- ✅ 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)
|
||||
---
|
||||
**Status**: ACTIVE
|
||||
|
||||
44
CODING_STANDARDS.md
Normal file
44
CODING_STANDARDS.md
Normal 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
65
DESIGN_SYSTEM.md
Normal 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
23
GEMINI.md
@@ -4,23 +4,22 @@ You are Gemini (Antigravity), operating on the TFM aInventory project.
|
||||
|
||||
**IMMEDIATE MANDATORY ACTION:**
|
||||
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).
|
||||
2. `PROJECT_ARCHITECTURE.md` (Contains the tech stack, data models, and system logic).
|
||||
3. `dev_docs/SESSION_STATE.md` (Contains the current handover status from the previous AI).
|
||||
1. `AI_MANDATES.md` (Operational constraints, Git rules, Handover protocols).
|
||||
2. `DESIGN_SYSTEM.md` (UI/UX standards, Colors, Typography).
|
||||
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:**
|
||||
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
|
||||
|
||||
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
|
||||
- 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)
|
||||
---
|
||||
**Status**: ACTIVE
|
||||
|
||||
322
PLAN.md
322
PLAN.md
@@ -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.
|
||||
@@ -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
67
README.md
@@ -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)
|
||||
|
||||
For production environments, Docker is the recommended deployment method:
|
||||
|
||||
```bash
|
||||
git clone <repository-url> 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
|
||||
|
||||
# Edit config/secrets.yaml with your JWT_SECRET_KEY and AI keys
|
||||
# Edit config/secrets.yaml with your keys
|
||||
nano config/secrets.yaml
|
||||
|
||||
# Deploy using the new Python deployment script
|
||||
# Deploy
|
||||
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
|
||||
|
||||
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
|
||||
* **Backend:** FastAPI (Python 3.12+)
|
||||
* **Frontend:** Next.js 15+ (React PWA) with responsive Tailwind CSS
|
||||
* **Database:** SQLite (SQLAlchemy) with Dexie.js (IndexedDB) for client-side sync.
|
||||
* **AI Engine:** Google Gemini (Primary) & Anthropic Claude (Fallback).
|
||||
* **Configuration:** [D-07] Consolidated YAML-based config in `config/` directory.
|
||||
|
||||
For more details on system logic, see **[PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md)**.
|
||||
## 🏗 Key Features
|
||||
- **Offline-First**: Continuous operation without network; background sync via IndexedDB.
|
||||
- **AI OCR**: Intelligent label extraction using Gemini & Claude.
|
||||
- **Enterprise Ready**: LDAP authentication, immutable audit logs, and SQLite WAL mode.
|
||||
- **PWA**: Installable on any mobile device.
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security & Constraints
|
||||
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)
|
||||
**Current Version**: 1.15.0
|
||||
**Status**: Active Development
|
||||
|
||||
@@ -49,10 +49,6 @@ A unified inventory management system that eliminates manual data entry through
|
||||
|
||||
## 5. Design & Operational Constraints
|
||||
- **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).
|
||||
- **StatCard Rule**: Numeric values MUST match label text size for balanced density.
|
||||
- **Database**: Single-instance SQLite (WAL mode). Multi-instance is v3+.
|
||||
Reference in New Issue
Block a user