context.md

🧠 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)