# 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:8906
*   **Frontend:** https://localhost:8909

### 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://<SERVER-IP>: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](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` |
| **ALLOWED_ORIGINS** | CORS-allowed domain origins (comma-separated) | `https://inventory.example.com,https://api.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
```bash
# 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](dev_docs/SECURITY_REPORT.md).

---

## 📜 AI Operational Rules
AI agents working on this project MUST follow the guidelines in [AI_RULES.md](AI_RULES.md).