# khoitran2003/human-face-analysis-ai-hackathon architecture

> Architecture diagram of the GitHub repository khoitran2003/human-face-analysis-ai-hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khoitran2003/human-face-analysis-ai-hackathon
- Repository: https://github.com/khoitran2003/human-face-analysis-ai-hackathon

## Overview

##### Project Type & Purpose
- This is a computer vision and machine learning application focused on analyzing human faces. Its objectives include emotion detection, age estimation, gender recognition, and facial feature extraction.
- The project serves both as an analysis tool and a learning example for AI-based face analysis. It includes training routines (for both classification and detection), as well as inference scripts and a web application interface.

##### Examination of the File Structure
- Top-Level Structure:
- Configuration Files: The “cfg” folder holds YAML configurations for both classifier and detection models, along with label definitions.
- Source Code: Under “source”, there are two main directories—“classification” and “detection”. Each contains scripts for data loading, model creation (e.g., modified ResNet for classification), and separate training routines.
- Inference Scripts: Files like “infer_image.py” and “infer_webcam.py” indicate support for real-time or image-based inference.
- Web Application: “webapp.py” suggests that a lightweight web server (likely built with Flask) is used to serve the analysis results, combined with “templates” (HTML) and “static” (JavaScript and assets) for the front-end.
- Uploaded and Results: “uploaded_images” and “results” directories store sample input media and output visualizations (screenshots).

##### Main Components
a. User Interface Layer:
- Frontend: Represent the “templates” and “static” directories. Describe how HTML pages, JavaScript, and CSS are used to create the UI.
- Uploaded Content: The component where users upload images or videos (represented by “uploaded_images”).

b. Web Server / API Layer:
- The “webapp.py” acts as the central hub for incoming requests. This is likely a Flask (or similar lightweight framework) based server which routes requests to perform inference and serve UI content.

c. Machine Learning Modules:
- Classification Module: Include components for data preparation, custom loss (e.g., focal loss), data loading, model (modified ResNet-50), and a training script. Note that these are found under “source/classification”.
- Detection Module: Similar to classification; include data customization (data preprocessing), separate training routines, and inference steps from “source/detection”.
- Modular ML pipelines with configuration nodes from the “cfg” folder to show how model parameters and labels are defined and consumed.
- Inference Scripts: “infer_image.py” and “infer_webcam.py” can be represented as entry points for non-web app based usage scenarios.

d. Model Checkpoints & Data:
- That the trained models (from the training pipelines) are saved as model checkpoint files (stored in the “checkpoint” folder, created during setup).
- Interactions where the web server (or inference scripts) loads these checkpoints in order to perform real-time predictions.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The system separates the web (user interaction) from the backend ML pipelines. This ensures that UI, business logic, and model inference/training remain distinct.
- Config-Driven Design: The “cfg” directory highlights external configuration which decouples parameter settings from code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external

    subgraph "Frontend"
        Templates["HTML Templates"]:::frontend
        Static["Static Assets"]:::frontend
    end

    UploadedImages["Uploaded Content Storage"]:::datastore

    WebServer["Web Server (webapp.py)"]:::backend

    subgraph "ML Modules"
        Classification["Classification Module"]:::ml
        Detection["Detection Module"]:::ml
    end

    Config["Configuration Management (cfg)"]:::config

    subgraph "Inference Scripts"
        InferImage["Inference Script (infer_image.py)"]:::backend
        InferWebcam["Inference Script (infer_webcam.py)"]:::backend
    end

    Checkpoints["Model Checkpoints"]:::datastore

    %% Connections from User
    User -->|"access"| Templates
    User -->|"access"| Static
    User -->|"upload"| UploadedImages

    %% Frontend to Web Server
    Templates -->|"request"| WebServer
    UploadedImages -->|"providesImage"| WebServer

    %% Web Server to ML Modules
    WebServer -->|"calls"| Classification
    WebServer -->|"calls"| Detection

    %% Configuration Management to ML Modules and Inference Scripts
    Config -->|"providesSettings"| Classification
    Config -->|"providesSettings"| Detection
    Config -->|"providesSettings"| InferImage
    Config -->|"providesSettings"| InferWebcam

    %% ML Modules saving models
    Classification -->|"savesModel"| Checkpoints
    Detection -->|"savesModel"| Checkpoints

    %% Inference Scripts interacting with ML Modules
    InferImage -->|"triggers"| Classification
    InferImage -->|"triggers"| Detection
    InferWebcam -->|"triggers"| Classification
    InferWebcam -->|"triggers"| Detection

    %% Click Events
    click Templates "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/tree/master/templates/"
    click Static "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/tree/master/static/"
    click UploadedImages "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/tree/master/uploaded_images/"
    click WebServer "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/blob/master/webapp.py"
    click Classification "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/tree/master/source/classification/"
    click Detection "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/tree/master/source/detection/"
    click Config "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/tree/master/cfg/"
    click InferImage "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/blob/master/infer_image.py"
    click InferWebcam "https://github.com/khoitran2003/human-face-analysis-ai-hackathon/blob/master/infer_webcam.py"

    %% Styles
    classDef frontend fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef backend fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef ml fill:#a9dfbf,stroke:#196f3d,stroke-width:2px;
    classDef config fill:#f5b7b1,stroke:#943126,stroke-width:2px;
    classDef datastore fill:#f9c2c2,stroke:#a93226,stroke-width:2px;
    classDef external fill:#d2b4de,stroke:#6c3483,stroke-width:2px;
```
