+--------------------------------------------------------------------------------------------------+
|                                  THE DECOUPLED AI WEB STACK                                       |
+--------------------------------------------------------------------------------------------------+
|                                                                                                  |
|  [Tier 1: Client Edge / Browser]                                                                 |
|  Next.js 16 + WebAssembly (Wasm) + MediaPipe Browser Workers                                     |
|  --> Executes instant zero-cost preprocessing, face detection & landmark mesh in 15ms            |
|                                                                                                  |
|                                           |  (Compressed Tensor Payloads / High-Res Assets)       |
|                                           v                                                      |
|                                                                                                  |
|  [Tier 2: Ingress & Orchestration Layer]                                                         |
|  Laravel 12 / Node.js API Gateway + Redis Queue + WebSocket Gateway                              |
|  --> Manages user authentication, rate-limiting, job dispatching, and real-time state telemetry  |
|                                                                                                  |
|                                           |  (Asynchronous Celery / Redis Streams)               |
|                                           v                                                      |
|                                                                                                  |
|  [Tier 3: Specialized Python AI Microservice Mesh]                                               |
|  Containerized FastAPI Workers + OpenCV + MediaPipe + PyTorch (Docker on GPU/CPU Nodes)           |
|  --> Executes complex classification, background segmentation & aesthetic scoring pipelines      |
|                                                                                                  |
+--------------------------------------------------------------------------------------------------+

// src/workers/faceLandmarkWorker.ts
import { FaceMesh, Results } from "@mediapipe/face_mesh";

let faceMeshInstance: FaceMesh | null = null;

function initializeFaceMesh() {
  faceMeshInstance = new FaceMesh({
    locateFile: (file) => `https://cdn.jsdelivr.net/npm/@mediapipe/face_mesh/${file}`
  });

  faceMeshInstance.setOptions({
    maxNumFaces: 1,
    refineLandmarks: true,
    minDetectionConfidence: 0.75,
    minTrackingConfidence: 0.75
  });

  faceMeshInstance.onResults((results: Results) => {
    if (!results.multiFaceLandmarks || results.multiFaceLandmarks.length === 0) {
      self.postMessage({ type: "DETECTION_ERROR", message: "No face detected in viewport" });
      return;
    }

    const landmarks = results.multiFaceLandmarks[0];

    // Compute key morphological measurements directly in the worker
    const morphologyMetrics = extractFacialMetrics(landmarks);

    self.postMessage({
      type: "DETECTION_SUCCESS",
      landmarks,
      metrics: morphologyMetrics
    });
  });
}

function extractFacialMetrics(landmarks: Array<{ x: number; y: number; z: number }>) {
  // Forehead width: Distance between left and right temple landmarks (54, 284)
  const foreheadWidth = Math.hypot(landmarks[284].x - landmarks[54].x, landmarks[284].y - landmarks[54].y);

  // Cheekbone width: Distance between zygomatic arches (234, 454)
  const cheekboneWidth = Math.hypot(landmarks[454].x - landmarks[234].x, landmarks[454].y - landmarks[234].y);

  // Jawline width: Distance between gonial angles (172, 397)
  const jawlineWidth = Math.hypot(landmarks[397].x - landmarks[172].x, landmarks[397].y - landmarks[172].y);

  // Facial height: Distance between trichion (top of forehead) and gnathion (chin tip: 10, 152)
  const faceHeight = Math.hypot(landmarks[152].x - landmarks[10].x, landmarks[152].y - landmarks[10].y);

  return {
    foreheadWidth,
    cheekboneWidth,
    jawlineWidth,
    faceHeight,
    ratioLengthToWidth: faceHeight / cheekboneWidth,
    ratioCheekToJaw: cheekboneWidth / jawlineWidth
  };
}

self.onmessage = async (e: MessageEvent) => {
  if (e.data.type === "INIT") {
    initializeFaceMesh();
  } else if (e.data.type === "PROCESS_FRAME" && faceMeshInstance) {
    await faceMeshInstance.send({ image: e.data.imageBitmap });
  }
};

// src/hooks/useFaceLandmarkDetection.ts
import { useEffect, useRef, useState, useCallback } from "react";

export function useFaceLandmarkDetection() {
  const workerRef = useRef<Worker | null>(null);
  const [metrics, setMetrics] = useState<any | null>(null);
  const [isProcessing, setIsProcessing] = useState(false);

  useEffect(() => {
    // Spin up Web Worker on component mount
    const worker = new Worker(new URL("../workers/faceLandmarkWorker.ts", import.meta.url), {
      type: "module"
    });

    worker.postMessage({ type: "INIT" });

    worker.onmessage = (e) => {
      if (e.data.type === "DETECTION_SUCCESS") {
        setMetrics(e.data.metrics);
        setIsProcessing(false);
      }
    };

    workerRef.current = worker;
    return () => worker.terminate();
  }, []);

  const analyzeImage = useCallback(async (imageElement: HTMLImageElement) => {
    if (!workerRef.current) return;
    setIsProcessing(true);

    // Create high-performance ImageBitmap for zero-copy worker transfer
    const imageBitmap = await createImageBitmap(imageElement);
    workerRef.current.postMessage({ type: "PROCESS_FRAME", imageBitmap }, [imageBitmap]);
  }, []);

  return { analyzeImage, metrics, isProcessing };
}

# microservices/ai_vision/main.py
from fastapi import FastAPI, UploadFile, File, HTTPException, BackgroundTasks
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
import cv2
import numpy as np
import mediapipe as mp
import asyncio
from typing import Dict, Any

app = FastAPI(
    title="Enterprise AI Computer Vision Microservice",
    version="2.0.0",
    description="High-throughput facial analysis and image segmentation engine"
)

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://testdebelleza.com", "https://faceshapedetector.ai"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# Global model cache to avoid re-instantiating models per request
mp_face_mesh = mp.solutions.face_mesh.FaceMesh(
    static_image_mode=True,
    max_num_faces=1,
    refine_landmarks=True,
    min_detection_confidence=0.8
)

class SymmetryReport(BaseModel):
    golden_ratio_score: float
    bilateral_symmetry_percentage: float
    canthal_tilt_degrees: float
    facial_classification: str
    diagnostics: Dict[str, Any]

def calculate_facial_symmetry(image_np: np.ndarray) -> SymmetryReport:
    """
    Executes advanced facial symmetry and golden ratio mathematical analysis.
    """
    h, w, _ = image_np.shape
    results = mp_face_mesh.process(cv2.cvtColor(image_np, cv2.COLOR_BGR2RGB))

    if not results.multi_face_landmarks:
        raise ValueError("No facial features identified in provided image buffer.")

    landmarks = results.multi_face_landmarks[0].landmark

    # 1. Bilateral Symmetry Analysis: Compare Left vs Right Facial Planes
    # Left eye outer corner (33), Right eye outer corner (263), Nose tip (1)
    p_left_eye = np.array([landmarks[33].x * w, landmarks[33].y * h])
    p_right_eye = np.array([landmarks[263].x * w, landmarks[263].y * h])
    p_nose = np.array([landmarks[1].x * w, landmarks[1].y * h])

    # Calculate horizontal alignment and tilt
    eye_delta = p_right_eye - p_left_eye
    canthal_tilt = float(np.degrees(np.arctan2(eye_delta[1], eye_delta[0])))

    # Compute distances from mid-facial sagittal axis
    midline_x = p_nose[0]
    left_dist = abs(p_left_eye[0] - midline_x)
    right_dist = abs(p_right_eye[0] - midline_x)
    symmetry_diff = abs(left_dist - right_dist) / max(left_dist, right_dist)
    bilateral_symmetry = round((1.0 - symmetry_diff) * 100, 2)

    # 2. Golden Ratio Assessment (Phi = 1.618)
    # Trichion to Menton / Zygomatic Width
    face_height = np.linalg.norm(
        np.array([landmarks[10].x * w, landmarks[10].y * h]) - 
        np.array([landmarks[152].x * w, landmarks[152].y * h])
    )
    face_width = np.linalg.norm(
        np.array([landmarks[234].x * w, landmarks[234].y * h]) - 
        np.array([landmarks[454].x * w, landmarks[454].y * h])
    )
    measured_ratio = face_height / face_width
    phi = 1.61803398875
    golden_ratio_score = round(max(0, 100 - (abs(measured_ratio - phi) / phi * 100)), 2)

    return SymmetryReport(
        golden_ratio_score=golden_ratio_score,
        bilateral_symmetry_percentage=bilateral_symmetry,
        canthal_tilt_degrees=round(canthal_tilt, 2),
        facial_classification="Harmonic Proportional" if bilateral_symmetry > 88 else "Distinctive Natural",
        diagnostics={
            "measured_ratio": round(measured_ratio, 4),
            "ideal_phi": 1.618,
            "landmarks_evaluated": 468
        }
    )

@app.post("/api/v1/analyze-symmetry", response_model=SymmetryReport)
async def analyze_symmetry_endpoint(file: UploadFile = File(...)):
    if file.content_type not in ["image/jpeg", "image/png", "image/webp"]:
        raise HTTPException(status_code=415, detail="Unsupported media format. Submit JPEG, PNG, or WebP.")

    try:
        # Read raw image bytes asynchronously without blocking event loop
        contents = await file.read()
        nparr = np.frombuffer(contents, np.uint8)
        img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)

        if img is None:
            raise HTTPException(status_code=422, detail="Corrupted image binary.")

        # Run CPU-bound image computation in a dedicated thread pool
        loop = asyncio.get_event_loop()
        report = await loop.run_in_executor(None, calculate_facial_symmetry, img)
        return report

    except ValueError as ve:
        raise HTTPException(status_code=422, detail=str(ve))
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Internal inference failure: {str(e)}")

+-----------------------------------------------------------------------------------------------+
|                                ASYNCHRONOUS AI PROCESSING PIPELINE                            |
+-----------------------------------------------------------------------------------------------+
|                                                                                               |
|  [Client Web Browser]                                                                         |
|            |                                                                                  |
|            |  1. POST /api/jobs (Upload Photo)                                                |
|            v                                                                                  |
|  [API Gateway (Laravel / Node)]                                                               |
|            |                                                                                  |
|            |  2. Enqueue Job & Return Job ID: `job_8f1a3b` (<15ms)                             |
|            +----------------------------------------------> [Client: Show Animated Scanner]   |
|            |                                                                                  |
|            v                                                                                  |
|  [Redis Stream: `ai_inference_queue`]                                                         |
|            |                                                                                  |
|            |  3. Worker Pool Consumes Jobs (Controlled Concurrency: 8 workers max)            |
|            v                                                                                  |
|  [Python FastAPI Worker Nodes]                                                                |
|            |                                                                                  |
|            |  4. Process OpenCV & Deep Model (650ms)                                          |
|            v                                                                                  |
|  [Redis Pub/Sub: `job_results:job_8f1a3b`]                                                    |
|            |                                                                                  |
|            |  5. Emit WebSocket Notification                                                  |
|            v                                                                                  |
|  [Client Web Browser: Renders Result Card Instantaneously!]                                   |
|                                                                                               |
+-----------------------------------------------------------------------------------------------+

# Defense against Image Bombs
def sanitize_uploaded_image(raw_bytes: bytes, max_dim: int = 1920) -> np.ndarray:
    nparr = np.frombuffer(raw_bytes, np.uint8)
    img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)

    if img is None:
        raise ValueError("Invalid image file.")

    h, w = img.shape[:2]
    if max(h, w) > max_dim:
        scale = max_dim / max(h, w)
        img = cv2.resize(img, (int(w * scale), int(h * scale)), interpolation=cv2.INTER_AREA)

    return img