chore: major codebase cleanup and documentation consolidation

2026-04-23 11:44:33 +03:00
parent 0e356e6c89
commit 8aeabcf1f5
72 changed files with 380 additions and 28893 deletions
--- a/README.md
+++ b/README.md
@@ -4,122 +4,49 @@ A unified, offline-first Inventory Management System built as a Progressive Web

 ---

-## 🛠 Project Modes
+## 🚀 Quick Start (Production)

-This project supports three distinct operational modes:
+For production environments, Docker is the recommended deployment method:

-### 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
+```bash
+git clone <repository-url> tfm-inventory
+cd tfm-inventory
+cp inventory.env.example inventory.env
+# Edit inventory.env with your JWT_SECRET_KEY and AI keys
+./deploy.sh production
+```

-### 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
+- **Frontend**: http://localhost:8917 (or https://localhost:8909 via proxy)
+- **Backend API**: http://localhost:8916/docs

-### 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
+For detailed deployment instructions (Docker vs Standalone), see **[DEPLOYMENT.md](DEPLOYMENT.md)**.

 ---

-## 📦 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).
+*   **AI Engine:** Google Gemini (Primary) & Anthropic Claude (Fallback).

-## 🧪 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).
+For more details on system logic, see **[PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md)**.

 ---

-## 🔐 Security & Production Deployment
+## 🔐 Security & Constraints
+AI agents and developers MUST strictly follow the rules defined in **[AI_RULES.md](AI_RULES.md)**.

-### 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).
+- **No Uppercase UI**: All labels/headers must be normal case.
+- **No Bold Fonts**: Text hierarchy is achieved through size and color.
+- **Offline-First**: All features must function without an active network connection.

 ---

-## 📜 AI Operational Rules
-AI agents working on this project MUST follow the guidelines in [AI_RULES.md](AI_RULES.md).
+## 📦 Production Distribution
+To generate a clean production package:
+`python3 scripts/save_version.py --patch` (or `--minor`/`--major`)
+
+---
+
+**Last Updated**: 2026-04-23  
+**Version**: 1.14.6