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:

Use the AI shortcut command: save-version.
Alternatively, run ./export_prod.sh manually.
A .zip archive will be created (e.g., aInventory-PROD-v1.7.0.zip).
A backup branch v.1.3.x will 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" 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)
Multi-AI Selection & Secure Config (v1.9.23):
- Support for both Google Gemini and Anthropic Claude for AI label extraction.
- Dynamically configurable AI providers via the Admin Dashboard.
- Centralized ConfigManager for secure API key and environment management.
Admin UI Standardization: Refactored Admin page with unified StatCards and secure input masking for system credentials.

🏗 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.

Languages

Python 95.7%

TypeScript 1.4%

Cython 1.1%

C 1%

C++ 0.6%