# hai4h/yolo-human-face-detection architecture

> Architecture diagram of the GitHub repository hai4h/yolo-human-face-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hai4h/yolo-human-face-detection
- Repository: https://github.com/hai4h/yolo-human-face-detection

## Overview

##### Project type and purpose
- This is a full-stack, real-time web application for person/face detection and emotion recognition.
- It uses a vanilla JavaScript/CSS/HTML frontend, a Python FastAPI backend, and AI models (YOLO & TensorFlow/TFLite) for inference.

##### Main components
a. Web Frontend
- Static assets (frontend/index.html, CSS, JS) served over HTTPS by run_server.py using SSL certs in ssl/
- JS modules: camera.js (WebRTC capture), detection.js (send frame & parse response), stats.js (update metrics), ui.js, state.js, config.js
b. FastAPI Backend
- Entry point: backend/main.py (defines /process_frame and /health endpoints)
- app/config.py (model paths, thresholds), app/models.py (model loader), app/box_detector.py (orchestrates inference), backend/db_utils.py (optional logging/persistence)
c. AI Model Layer
- YOLO person & face detectors (.pt files in models/)
- Emotion & human-action recognizers (.tflite, .h5 files)
d. Optional Offline Training & Utilities
- scripts/ for training, conversion, benchmarking
- dataset/ for training data

##### Relationships and data flow
- Browser (user) ▶︎ captures video frames via camera.js
- Frontend ▶︎ POST multipart/form-data to FastAPI /process_frame (frame JPEG)
- FastAPI ▶︎ box_detector loads models, runs YOLO person→face detection, then TensorFlow/TFLite emotion inference
- FastAPI ▶︎ returns JSON payload (persons, faces, person_boxes, face_boxes with emotion)
- Frontend ▶︎ detection.js & stats.js update UI

##### Architectural patterns & design principles
- Separation of Concerns:
- Frontend MVC-like structure (camera, detection, UI, state, stats)
- Backend modularization (config, model loader, detection logic, API)
- Asynchronous I/O: FastAPI + Uvicorn for concurrency
- Offline vs. Online: real-time serving vs. batch/utility scripts

##### Detail without over-splitting
- Every runtime module but focus on logical groupings
- SSL termination at the boundary (HTTPS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        A["frontend/index.html"]:::frontend
        B["CSS Styles (frontend/css/)"]:::frontend
        subgraph "JS Modules"
            direction TB
            C1["camera.js"]:::frontend
            C2["detection.js"]:::frontend
            C3["stats.js"]:::frontend
            C4["ui.js"]:::frontend
            C5["state.js"]:::frontend
            C6["config.js"]:::frontend
        end
    end

    %% HTTPS Server
    D["run_server.py\n(HTTPS Server)"]:::backend
    subgraph "SSL Certificates"
        direction TB
        D1["ssl/fullchain.pem"]:::storage
        D2["ssl/privkey.pem"]:::storage
    end

    %% Backend Layer
    subgraph "Backend API"
        direction TB
        E["backend/main.py\n(/process_frame & /health)"]:::backend
        F["backend/db_utils.py\n(Optional DB)"]:::backend
        G["app/config.py"]:::backend
        H["app/models.py"]:::backend
        I["app/box_detector.py"]:::backend
    end

    %% AI Models Storage
    subgraph "AI Models Storage"
        direction TB
        J["YOLO & Face Detectors\n(models/*.pt)"]:::storage
        K["Emotion & Action Models\n(models/*.tflite/.h5)"]:::storage
    end

    %% Offline Training & Utilities
    subgraph "Offline Training & Utilities"
        direction TB
        style Offline stroke-dasharray: 5 5
        L["scripts/"]:::offline
        M["dataset/"]:::offline
        N["best.pt"]:::storage
    end

    %% Data Flow
    A -->|"Render UI"| C1
    C1 -->|"Capture Frame"| C2
    C2 -->|"POST Video Frame (JPEG)"| E
    E -->|"calls box_detector"| I
    I -->|"Load Models at Startup"| H
    H --> J
    H --> K
    I -->|"YOLO detection"| J
    I -->|"Emotion inference"| K
    I -->|"Optional Save Metrics"| F
    I -->|"Return JSON Results"| E
    E -->|"Return JSON"| C2
    C2 -->|"Update Stats"| C3
    C2 -->|"Update UI"| C4

    %% Server to Frontend
    D --> A
    D --> B
    D --> C1
    D1 --> D
    D2 --> D

    %% Offline Pipeline
    L --> M
    L --> N
    M --> N

    %% Click Events
    click A "https://github.com/hai4h/yolo-human-face-detection/blob/main/frontend/index.html"
    click B "https://github.com/hai4h/yolo-human-face-detection/tree/main/frontend/css/"
    click C1 "https://github.com/hai4h/yolo-human-face-detection/blob/main/frontend/js/camera.js"
    click C2 "https://github.com/hai4h/yolo-human-face-detection/blob/main/frontend/js/detection.js"
    click C3 "https://github.com/hai4h/yolo-human-face-detection/blob/main/frontend/js/stats.js"
    click C4 "https://github.com/hai4h/yolo-human-face-detection/blob/main/frontend/js/ui.js"
    click C5 "https://github.com/hai4h/yolo-human-face-detection/blob/main/frontend/js/state.js"
    click C6 "https://github.com/hai4h/yolo-human-face-detection/blob/main/frontend/js/config.js"
    click D "https://github.com/hai4h/yolo-human-face-detection/blob/main/run_server.py"
    click D1 "https://github.com/hai4h/yolo-human-face-detection/blob/main/ssl/fullchain.pem"
    click D2 "https://github.com/hai4h/yolo-human-face-detection/blob/main/ssl/privkey.pem"
    click E "https://github.com/hai4h/yolo-human-face-detection/blob/main/backend/main.py"
    click F "https://github.com/hai4h/yolo-human-face-detection/blob/main/backend/db_utils.py"
    click G "https://github.com/hai4h/yolo-human-face-detection/blob/main/app/config.py"
    click H "https://github.com/hai4h/yolo-human-face-detection/blob/main/app/models.py"
    click I "https://github.com/hai4h/yolo-human-face-detection/blob/main/app/box_detector.py"
    click J "https://github.com/hai4h/yolo-human-face-detection/tree/main/models/"
    click K "https://github.com/hai4h/yolo-human-face-detection/tree/main/models/"
    click L "https://github.com/hai4h/yolo-human-face-detection/tree/main/scripts/"
    click M "https://github.com/hai4h/yolo-human-face-detection/tree/main/dataset/"
    click N "https://github.com/hai4h/yolo-human-face-detection/blob/main/best.pt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD8,stroke:#333,stroke-width:1px
    classDef ai fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef storage fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef offline fill:#F8F8F8,stroke:#AAA,stroke-dasharray:5 5
```
