# 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

### Frontend Quality Audit (v1.10.15)
- **Accessibility:** Removed decorative gradients, added focus-visible indicators, semantic HTML landmarks (`<main>`)
- **Responsiveness:** Fixed Scanner viewport responsive sizing (was fixed w-[85%], now fluid)
- **Motion:** Corrected prefers-reduced-motion implementation for motion-sensitive users
- **Keyboard Navigation:** Enhanced admin page with proper focus management and ARIA labels
- **Audit Score:** 14/20 → 17+/20 (Good rating, production-ready)

### Mobile-First Responsive Design (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)
- **Admin UI Standardization:** Refactored Admin page with unified StatCards and secure input masking for system credentials.
- **Modular Admin Architecture (v1.10.0):** 
  - Decomposed monolithic pages into domain-specific components: `IdentityManager`, `DatabaseManager`, `LdapManager`, `AiManager`, and `CategoryManager`.
  - Centralized state logic into a custom `useAdmin` hook for improved maintainability.
  - Split backend admin endpoints into specific routers (`backups`, `config`) for better scalability.
  - Optimized Docker configuration with persistent binary paths and fixed log-piping via `su-exec`.

## 🏗 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](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).