Daniel Bedeleanu
3e60bb1707
Replace static import of tesseract.js (500KB) with dynamic import in Scanner component. Library now only loads when OCR recognition is actually performed, not on initial page load. Performance Impact: - Removes 500KB from initial bundle - Library only loads when user activates OCR mode - Preload strategy in page.tsx still works (loads on-demand if scanner opened) - No functional change; same behavior, faster initial load Implementation: - Remove static import from Scanner.tsx (line 6) - Replace with dynamic import at point of use (line 166+) - page.tsx preloadOCR already uses dynamic import (no change needed) - Improves initial page load time significantly Build: Passes with zero errors. Compile time: 2.4s.
TFM aInventory (2026 Edition)
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.
🛠 Project Modes
This project supports three distinct operational modes:
1. 🚀 Development Mode (Bare-Metal)
Ideal for local development on macOS/Linux.
- Command:
./start_server.sh - Details: Runs FastAPI (backend) and Next.js (frontend) in development mode. Uses
local-ssl-proxyfor HTTPS. - Backend: http://localhost:8916
- Frontend: https://localhost:8919
2. 🐳 Docker Mode (Recommended for Production)
Isolated and portable container stack.
- Command:
docker-compose up -d --build - Details: Uses Caddy as a reverse proxy for HTTPS. Persistent data and logs are mapped to
./dataand./logs. - Access: https://localhost:8909
3. 🐧 Standalone Linux Mode (Systemd)
Native Linux installation (Alma/Debian/Ubuntu) without Docker dependencies.
- Installation:
sudo ./install_service.sh - Execution:
sudo systemctl start inventory - Details: Compiles the frontend for production and manages the entire stack as a system service.
- Access: https://:8909
📦 Production Distribution & Versioning
To generate a clean production package and snapshot the current state:
- Use the AI shortcut command:
save-version. - Alternatively, run
./export_prod.shmanually. - A
.ziparchive will be created (e.g.,aInventory-PROD-v1.7.0.zip). - A backup branch
v.1.3.xwill be created automatically.
🎨 Recent UI/UX Improvements (v1.9.21+)
Mobile-First Responsive Design
- StatCard Component: Reusable, responsive stat display component for mobile phones
- Two-column flexbox layout (label left, number right) prevents text overflow on narrow screens
- Responsive font sizing:
text-sm md:text-base(labels),text-lg md:text-xl(numbers) - Automatic label truncation with ellipsis for long text
- Accessible markup with
role="status"andaria-hiddenattributes
- Pages Updated: Inventory (Categories, Item Types, Total Boxes), Logs (Total Events, Check in/out), Admin (Local Archives)
- Tested on: iPhone SE (375px), iPhone 12 (390px), iPhone 14 Pro Max (430px), tablets (768px), desktop (1024px)
- Admin UI Standardization: Refactored Admin page with unified StatCards and secure input masking for system credentials.
- Modular Admin Architecture (v1.10.0):
- Decomposed monolithic pages into domain-specific components:
IdentityManager,DatabaseManager,LdapManager,AiManager, andCategoryManager. - Centralized state logic into a custom
useAdminhook for improved maintainability. - Split backend admin endpoints into specific routers (
backups,config) for better scalability. - Optimized Docker configuration with persistent binary paths and fixed log-piping via
su-exec.
- Decomposed monolithic pages into domain-specific components:
🏗 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.
- Proxy: Caddy (Docker) or local-ssl-proxy (Standalone/Dev).
- AI Engine: Google Gemini (Generative AI SDK).
🧪 Testing & Verification (v1.10.0+)
The project includes a comprehensive testing suite to ensure architectural stability:
- Backend:
pytestintegration tests with in-memory database mocks.- Run:
PYTHONPATH=. ./backend/venv/bin/pytest backend/tests/
- Run:
- Frontend:
vitestunit tests for custom React hooks and state logic.- Run:
npm run test(requires Node 20+)
- Run:
For more details, see PROJECT_ARCHITECTURE.md.
🔐 Security & Production Deployment
Critical Environment Variables
The application requires the following environment variables for production deployment:
| Variable | Purpose | Example |
|---|---|---|
| JWT_SECRET_KEY | JWT token signing key (REQUIRED for production) | openssl rand -hex 32 |
| EXTRA_ALLOWED_ORIGINS | Extra IPs or FQDNs for CORS (Tailscale, VPN, etc.) | 100.78.182.27,inventory.local |
| ALLOWED_ORIGINS | CORS-allowed domain origins (automatically includes LOCAL_IP) | https://inventory.example.com |
| DATA_DIR | SQLite database location | /app/data |
| LOGS_DIR | Application logs directory | /app/logs |
⚠️ IMPORTANT:
- In development,
JWT_SECRET_KEYdefaults to an ephemeral random value, which is reset on restart. - For production, set
JWT_SECRET_KEYto a stable, long random string and store it in a secrets manager (AWS Secrets, HashiCorp Vault, etc.). ALLOWED_ORIGINSmust be set to your actual production domain(s). Wildcard origins (*) are rejected whenallow_credentials=True.
Docker Production Deployment
# Set environment variables
export JWT_SECRET_KEY="$(openssl rand -hex 32)"
export ALLOWED_ORIGINS="https://your-domain.com"
# Launch stack
docker-compose up -d --build
🌐 Network & Port Customization
The application uses a central configuration file for all network settings:
- Location:
config/network_config.env - Purpose: Change the
SERVER_IP(default:192.168.84.113) and reserved ports (8906-8909). - Mechanism: Startup scripts automatically sync these settings to the frontend and Docker environment.
For detailed security audit report, see dev_docs/SECURITY_REPORT.md.
📜 AI Operational Rules
AI agents working on this project MUST follow the guidelines in AI_RULES.md.