86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# 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:8000
|
|
* **Frontend:** https://localhost:3003
|
|
|
|
### 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:3003
|
|
|
|
### 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>:3003
|
|
|
|
---
|
|
|
|
## 📦 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.3.6.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
|
|
```
|
|
|
|
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).
|