10d75619bf
- Added StatCard component description to README - Updated frontend architecture in PROJECT_ARCHITECTURE.md - Documented responsive design improvements (v1.9.21+) - Mobile-first responsive design for inventory management
104 lines
4.6 KiB
Markdown
104 lines
4.6 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: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://<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.
|
|
|
|
---
|
|
|
|
## 🎨 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)
|
|
|
|
## 🏗 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).
|
|
|
|
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` |
|
|
| **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
|
|
```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).
|