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-proxy for 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 ./data and ./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:

1. Use the AI shortcut command: save-version.
2. Alternatively, run ./export_prod.sh manually.
3. A .zip archive will be created (e.g., aInventory-PROD-v1.7.0.zip).
4. A backup branch v.1.3.x will be created automatically.

---

🎨 Recent UI/UX Improvements

Frontend Quality Audit (v1.10.15)

• Accessibility: Removed decorative gradients, added focus-visible indicators, semantic HTML landmarks (<main>)
• Responsiveness: Fixed Scanner viewport responsive sizing (was fixed w-[85%], now fluid)
• Motion: Corrected prefers-reduced-motion implementation for motion-sensitive users
• Keyboard Navigation: Enhanced admin page with proper focus management and ARIA labels
• Audit Score: 14/20 → 17+/20 (Good rating, production-ready)

Mobile-First Responsive Design (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" and aria-hidden attributes
• 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, and CategoryManager.
  • Centralized state logic into a custom useAdmin hook 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.

🏗 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: pytest integration tests with in-memory database mocks.
  • Run: PYTHONPATH=. ./backend/venv/bin/pytest backend/tests/
• Frontend: vitest unit tests for custom React hooks and state logic.
  • Run: npm run test (requires Node 20+)

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_KEY defaults to an ephemeral random value, which is reset on restart.
• For production, set JWT_SECRET_KEY to a stable, long random string and store it in a secrets manager (AWS Secrets, HashiCorp Vault, etc.).
• ALLOWED_ORIGINS must be set to your actual production domain(s). Wildcard origins (*) are rejected when allow_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.