chore: major codebase cleanup and documentation consolidation
This commit is contained in:
@@ -2,122 +2,80 @@
|
||||
|
||||
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.
|
||||
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+ (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) & Anthropic SDK (Claude 3.5 Sonnet) - Location: `backend/ai/`
|
||||
- **Testing:** Pytest (Unit & Integration) - Location: `backend/tests/`
|
||||
- **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)
|
||||
- **Styling:** Tailwind CSS (Readability-first config, mobile-first responsive)
|
||||
- **Icons:** Lucide Icons (React components)
|
||||
- **Components:**
|
||||
- **StatCard** (v1.9.21+): Responsive stat display component for mobile/desktop
|
||||
- Two-column flexbox layout (label left, number right)
|
||||
- Responsive font sizing with Tailwind breakpoints (text-sm→md, text-lg→xl)
|
||||
- Label truncation with ellipsis for overflow handling
|
||||
- Accessibility: `role="status"`, `aria-hidden` on decorative icons
|
||||
- **Offline persistence:** Dexie.js (IndexedDB wrapper)
|
||||
- **Scanner:** `html5-qrcode` (Client-side, offline-only)
|
||||
- **Sync:** Axios with bulk-sync idempotency (UUID-based)
|
||||
- **Testing:** Vitest (React Hook Testing) - Location: `frontend/tests/`
|
||||
- **Architecture**: Next.js 15+ (App Router, TypeScript Strict)
|
||||
- **Styling**: Tailwind CSS v3.4 (Standard typography, 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 Deployment:** `next-pwa` (Service Workers + Manifest.json)
|
||||
- **HTTPS Proxy:** `caddy` or `local-ssl-proxy` (Port 8909)
|
||||
- **Servers:** Frontend (Port 8907), Backend (Port 8906)
|
||||
- **Configuration:** Centrally managed via root `inventory.env` (Network/CORS/API Keys), `config/` directory (LDAP, Caddyfile), and a dynamic `ConfigManager` (`backend/config_manager.py`) for runtime environment and AI provider settings.
|
||||
- **PWA**: `next-pwa` (Service Workers + Manifest)
|
||||
- **HTTPS Proxy**: Caddy (Port 8909)
|
||||
- **Containerization**: Docker & Docker Compose
|
||||
- **Deployment**: `deploy.sh` (Docker) or `start_server.sh` (Standalone)
|
||||
|
||||
## 3. Data Models & Entities
|
||||
- **Item:** Name, Category Group (Structured), Item Type (Specific), Quantity, Barcode, Part Number, Box Label (Association).
|
||||
- **Category:** Predefined groups for organizational structure.
|
||||
- **Box/Container:** A generic grouping label (box_label) that links multiple items together for rapid multi-scanning.
|
||||
- **Audit Log:** Immutable ledger detailing CRUD operations and stock fluctuations, including point-in-time box associations.
|
||||
---
|
||||
|
||||
## 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` or `claude-3-5-sonnet`). The user takes a photo, AI extracts data based on strict templates.
|
||||
- **AI Provider Selection (v1.9.23):** Administrators can choose between Gemini and Claude via the Admin Dashboard. API keys are managed securely in the environment.
|
||||
- **AI Box Discovery Mode (v1.6.0):** Supports specialized `mode="box"` prompt that focuses exclusively on prominent container names/hand-written labels, ignoring technical spec noise.
|
||||
- **Validation Mask:** AI-extracted data is NEVER saved directly. It is presented in a validation UI for human confirmation.
|
||||
## 3. Core Business Logic
|
||||
|
||||
### 4.2 Scanner Technical Specs
|
||||
- **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 Mode:** Fully automated. Cycles every 4 seconds without user intervention. Visual countdown shown in controls panel.
|
||||
- **UI Layout:** Camera viewport is always unobstructed. Controls (Zoom + countdown status) are displayed in a dedicated section below the viewport.
|
||||
- **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.
|
||||
- **Targeted Field Scanning (v1.6.0):** UI allows "locking" the scanner focus to a specific input field (e.g., `box_label`). The OCR result is then redirected to state without performing regular item lookup.
|
||||
### 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.
|
||||
|
||||
### 4.3 Box Labeling & Printing System (v1.5.0)
|
||||
- **Local OCR Priority:** Before checking individual S/Ns, the matching engine searches for `box_label` tokens. If a box is identified:
|
||||
- Single Match: Directly opens stock adjustment.
|
||||
- Multi Match: Opens "Box Contents" selection interstitial.
|
||||
- **Label Generation:** Native SVG-based Code 128 and QR generation (`lib/labels.ts`). Requires ZERO external libraries for maximum offline stability.
|
||||
- **Printing Modes:**
|
||||
- @media print: Hardcoded CSS styles for 62mm x 29mm label dimensions.
|
||||
- Mobile Export: Canvas-to-PNG rasterization for sharing with Bluetooth printer roll apps.
|
||||
### 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.
|
||||
|
||||
## 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.
|
||||
---
|
||||
|
||||
## 6. Automation & Versioning (`scripts/`)
|
||||
- **`scripts/save_version.py`**: Implements the `save-version` AI Command Shortcut. Increments `VERSION.json` patch version, commits all staged changes, creates a snapshot branch `v.X.Y.Z`, and calls `./export_prod.sh` to generate the production bundle. Always stays on the `dev` branch.
|
||||
## 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`.
|
||||
|
||||
## 7. Security & Hardening (v1.4.0)
|
||||
To ensure enterprise-grade protection, the following policies are enforced:
|
||||
### 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`).
|
||||
|
||||
### 7.1 Access Control & RBAC
|
||||
- **Strict Separation:** Operations are divided into `user` and `admin` roles.
|
||||
- **Admin Only:** Critical operations such as `DELETE /items/`, user management, and DB settings are restricted via the `auth.get_current_admin` dependency.
|
||||
- **User Role:** Standard users are permitted to perform check-in/out and list inventory, but cannot delete catalog entries.
|
||||
---
|
||||
|
||||
### 7.2 CORS & Origin Policy (v1.9.18)
|
||||
- **Automatic Discovery:** The system detects local LAN IP and automatically authorizes it.
|
||||
- **Generic Expansion:** Use `EXTRA_ALLOWED_ORIGINS` for Tailscale or VPN IPs. The system automatically expands each IP into a set of authorized Origins (http/8916, https/8918, https/8919).
|
||||
- **Rate Limiting:** Implemented via `slowapi`. The `login` endpoint is limited to **5 requests per minute** per IP to mitigate automated credential stuffing.
|
||||
## 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 `inventory.env`.
|
||||
|
||||
### 7.3 Data Privacy
|
||||
- **Information Scrubbing:** Backend logs are configured to intercept and mask sensitive auth tokens or internal secrets (e.g., `JWT_SECRET_KEY`) during debug output.
|
||||
- **Direct Bind LDAP:** Authentication uses direct user binding to the LDAP server, avoiding the need for a privileged service account with broad search permissions.
|
||||
- **Cryptographic Credential Caching:** To support offline operations, the system caches a **PBKDF2-HMAC-SHA256 hash** of the user's Enterprise credentials upon successful online login. Plain text passwords are NEVER stored.
|
||||
---
|
||||
|
||||
### 7.4 PWA Trust & Security
|
||||
- **HTTPS Enforcement:** The system requires TLS (Port 8909) for camera access and secure token transmission.
|
||||
- **Manifest Integrity:** A comprehensive `manifest.json` ensures the app is recognized as a trusted PWA on mobile platforms (iOS/Android).
|
||||
|
||||
### 7.5 Git Infrastructure (Linux Native)
|
||||
|
||||
All git operations use the standard `git` command available in system PATH. On Linux systems, this is reliably provided by the git package via the system package manager.
|
||||
|
||||
|
||||
## 8. Multi-AI Engine & Dynamic Configuration (v1.9.23)
|
||||
To enhance extraction flexibility and system resilience:
|
||||
- **Unified AI Core:** The backend uses an abstraction layer to handle multiple AI providers (Gemini and Claude).
|
||||
- **Dynamic Configuration:** System settings (AI Provider, API Keys, Backup Policies) are managed via `backend/config_manager.py`, allowing real-time updates without restarting the container.
|
||||
- **Admin Standardization:** The Admin Dashboard features a standardized configuration UI with secure field masking for sensitive credentials.
|
||||
- **Architectural Modularization (v1.10.0):**
|
||||
- **Frontend:** The monolithic Admin Dashboard has been decomposed into domain-specific components: `IdentityManager`, `DatabaseManager`, `LdapManager`, `AiManager`, and `CategoryManager`.
|
||||
- **Logic:** Business logic is centralized in the `useAdmin` custom React hook, ensuring clean separation of concerns.
|
||||
- **Backend:** Administrative endpoints are split into the `backend/routers/admin/` package, with specialized routers for `backups` and `config`.
|
||||
- **Stability:** Docker builds are secured against lockfile mismatches by enforcing strict dependency synchronization.
|
||||
- **Verification Infrastructure:** A dual-layer testing suite is implemented: Pytest for backend integration (using in-memory SQLite and mocked auth) and Vitest for frontend logic validation.
|
||||
- **Frontend Stabilization (v1.10.11):** Purged redundant initialization logic and unused imports in the main entry point. Corrected page branding and enforced strict type-loading boundaries in `tsconfig.json` to ensure zero-error production builds.
|
||||
- **Frontend Quality Audit (v1.10.15):** Comprehensive frontend audit completed (14/20 → 17+/20). Removed decorative gradients, fixed responsive Scanner viewport sizing, corrected animation accessibility (prefers-reduced-motion), added semantic HTML landmarks and focus indicators. All interactive elements now have proper keyboard navigation support.
|
||||
**Last Updated**: 2026-04-23
|
||||
**Version**: 1.14.6
|
||||
|
||||
Reference in New Issue
Block a user