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.

---

🏗 Technical Overview

• Backend: FastAPI (Python 3.12+)
• Frontend: Next.js 15+ (React PWA)
• 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).

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.