# 🧠 Project Context: ID Maker Studio (EL HELAL Pipeline)

This document provides a high-level overview of the project's intent, architecture, and critical technical state for developers and AI agents.

---

## 🎯 Project Intent
**ID Maker Studio** is a professional-grade image processing pipeline designed for **EL HELAL Studio**. Its primary goal is to automate the conversion of raw student portraits into high-resolution (300 DPI), print-ready ID sheets. 

The system handles everything from blemish removal and color grading to complex Arabic typography and branding.

---

## 🏗 High-Level Architecture

The project is strictly modular, separating core business logic from user interfaces.

### 1. The Brain (`/core`)
- **Pipeline Orchestration:** Sequentially runs 5 critical steps.
- **AI Logic:**
    - **Crop:** OpenCV-based face detection (5:7 ratio).
    - **Background Removal:** BiRefNet (RMBG-2.0) running on CPU (quantized).
    - **Retouching:** MediaPipe Face Mesh + Frequency Separation (preserves 100% skin texture).
    - **Color Steal:** Custom algorithm to learn and apply professional color curves.
- **Layout Engine:** Composite engine using Pillow. Handles complex Arabic script via manual shaping and reordering.

### 2. The Interfaces
- **Web Interface (`/web`):** The primary production tool. Built with FastAPI and a localized Arabic (RTL) frontend.
    - **3-Column Layout:** Queue (Right) — Preview (Center) — Options & Settings (Left).
    - **Dark/Light Theme:** Toggleable via header button, persisted in localStorage.
    - **Batch Processing Counter:** Shows `1/5`, `2/5`... overlay with dim background during batch processing.
    - **Per-Image Delete:** Hover delete button on each queue item.
    - **Settings API:** Real-time slider-based tuning of retouch sensitivity, skin smoothing, font sizes — saved to `config/settings.json`.
    - **Keyboard Shortcuts:** Arrow navigation, Delete, Enter (save & next), Ctrl+S (process), Escape.
    - **Before/After Toggle:** Quick comparison between original and processed result.
    - **Zoom Modal:** Scroll-wheel zoom for detailed inspection.
    - **Mobile Drawer:** Responsive drawer for queue on mobile devices.
- **Desktop GUI (`/gui`):** Legacy Tkinter application for offline machine usage.

### 3. Data & Config
- **`/storage`:** Managed directory for uploads, processing, and results.
- **`/config`:** Centralized `settings.json` for real-time layout tuning (DPI, margins, font sizes).
- **`/assets`:** Branding marks and font files.

---

## 🚀 Deployment & Environment

- **Infrastructure:** Optimized for **Docker** and **Hugging Face Spaces**.
- **Hardware Context:** Targeted for **2 CPUs / 16GB RAM**. 
    - RAM allows for large image buffers.
    - CPU is the bottleneck; inference is sequential and quantized.
- **Binary Management:** Uses a hybrid approach. Smaller assets in Git; critical fonts are **automatically downloaded from GitHub** during Docker build to bypass Git LFS issues.

---

## ⚠️ Critical Technical "Gotchas"

- **Arabic Rendering:** In the container environment (standard LTR), Arabic is rendered by:
    1. Reshaping characters (connecting letters).
    2. **Manually reversing** the string characters to ensure correct visual flow without requiring `libraqm`.
- **MediaPipe Stability:** Explicitly imports submodules and includes safety checks to skip retouching if binary dependencies fail to initialize.
- **Transformers Monkeypatch:** Contains deep patches in `process_images.py` to handle `transformers 4.50+` tied-weight and meta-tensor bugs on CPU.
- **Dynamic Config:** `layout_engine.py` reloads `settings.json` on every request to allow "live" tuning of the output.

---

## 📂 Quick File Map
- `web/server.py`: FastAPI entry point. Includes Settings API (`GET/POST /settings`).
- `web/web_storage/index.html`: 3-column RTL frontend (Queue | Preview | Options).
- `core/layout_engine.py`: Final sheet composition logic.
- `core/retouch.py`: Advanced skin processing.
- `config/settings.json`: Live-reloadable settings (retouch sensitivity, font sizes, etc.).
- `Dockerfile`: Production environment definition.
- `tools/problems.md`: Historical log of technical hurdles and fixes.

---

*Last Updated: February 2026 — Web UI v2 (3-Column Layout, Batch Counter, Theme Toggle)*