# justadudewhohacks/face-api.js-models architecture

> Architecture diagram of the GitHub repository justadudewhohacks/face-api.js-models, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justadudewhohacks/face-api.js-models
- Repository: https://github.com/justadudewhohacks/face-api.js-models

## Overview

##### Project type and purpose
- This is an open-source model‐distribution package for face-api.js. It bundles multiple pre-trained deep-learning models (e.g., age/gender, face landmarks, MTCNN, Tiny YOLOv2) in both quantized (“shard” + manifest JSON) and uncompressed (“.weights”) forms.
- The README confirms: “Uncompressed and quantized models used by face-api.js.”

##### File structure
- Top‐level directories each represent one model variant:
- age_gender_model
- face_expression
- face_landmark_68
- face_landmark_68_tiny
- face_recognition
- mtcnn
- proto (contains a .pbtxt config file)
- ssd_mobilenetv1
- tiny_face_detector
- tiny_yolov2
- tiny_yolov2_separable_conv
- uncompressed (flat .weights files)
- Within each quantized model folder:
– model-shardN files (binary shards)
– model-weights_manifest.json (lists shard files & metadata)
- The uncompressed folder bundles end-to-end weight blobs for environments that don’t use shards.

##### README for additional insights
- Key dependencies implied: face-api.js (which itself builds on TensorFlow.js for inference).

##### Details & essential elements
– Note the two distribution types: quantized shards + manifest vs. single uncompressed weights
– Annotate lazy-loading behavior: models fetched only upon detection API calls
– Show optional config path (proto/ssd_mobilenet_face_optimized_v2.pbtxt) if the app needs custom SSD settings

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    ConsumerApp["Consumer App"]:::app
    ConsumerApp -->|"calls face-api.js APIs"| FaceAPI["face-api.js Library"]:::lib

    %% Library & Backend
    FaceAPI -->|"loads model via tfjs.loadGraphModel()"| TFJS["TensorFlow.js Backend"]:::lib

    %% Registry & Manifests
    TFJS --> Registry["Models Registry / Manifests"]:::static
    subgraph "Models Registry / Manifests"
        AGE_MAN["age_gender_model-weights_manifest.json"]:::static
        FE_MAN["face_expression_model-weights_manifest.json"]:::static
        FL68_MAN["face_landmark_68_model-weights_manifest.json"]:::static
        FL68T_MAN["face_landmark_68_tiny_model-weights_manifest.json"]:::static
        FR_MAN["face_recognition_model-weights_manifest.json"]:::static
        MTCNN_MAN["mtcnn_model-weights_manifest.json"]:::static
        SSD_MAN["ssd_mobilenetv1_model-weights_manifest.json"]:::static
        TFD_MAN["tiny_face_detector_model-weights_manifest.json"]:::static
        TY_MAN["tiny_yolov2_model-weights_manifest.json"]:::static
        TYSC_MAN["tiny_yolov2_separable_conv_model-weights_manifest.json"]:::static
    end
    Registry -->|"JSON manifest URLs"| CDN

    %% Static Hosting
    subgraph "CDN / Static Model Hosting"
        AGE_DIR["age_gender_model/"]:::static
        FE_DIR["face_expression/"]:::static
        FL68_DIR["face_landmark_68/"]:::static
        FL68T_DIR["face_landmark_68_tiny/"]:::static
        FR_DIR["face_recognition/"]:::static
        MTCNN_DIR["mtcnn/"]:::static
        SSD_DIR["ssd_mobilenetv1/"]:::static
        TFD_DIR["tiny_face_detector/"]:::static
        TY_DIR["tiny_yolov2/"]:::static
        TYSC_DIR["tiny_yolov2_separable_conv/"]:::static
        UNC_DIR["uncompressed/"]:::static
    end

    %% Model Shards & Weights
    CDN -->|"fetch manifest shards"| Quantized["Quantized Model Shards"]:::static
    CDN -->|"fetch full weights"| Uncompressed["Uncompressed Weights Bundle"]:::static

    subgraph "Quantized Model Shards"
        AGE_SH1["age_gender_model-shard1"]:::static
        FR_SH1["face_recognition_model-shard1"]:::static
        FR_SH2["face_recognition_model-shard2"]:::static
        TY_SH1["tiny_yolov2_model-shard1"]:::static
        TY_SH2["tiny_yolov2_model-shard2"]:::static
        TY_SH3["tiny_yolov2_model-shard3"]:::static
        TY_SH4["tiny_yolov2_model-shard4"]:::static
    end
    Quantized --> TFJS

    subgraph "Uncompressed Weights"
        UNC_AG["uncompressed/age_gender_model.weights"]:::static
        UNC_FE["uncompressed/face_expression_model.weights"]:::static
        UNC_FL68["uncompressed/face_landmark_68_model.weights"]:::static
        UNC_FL68T["uncompressed/face_landmark_68_tiny_model.weights"]:::static
        UNC_FR["uncompressed/face_recognition_model.weights"]:::static
        UNC_MTCNN["uncompressed/mtcnn_model.weights"]:::static
        UNC_SSD["uncompressed/ssd_mobilenetv1.weights"]:::static
        UNC_TFD["uncompressed/tiny_face_detector_model.weights"]:::static
        UNC_TY["uncompressed/tiny_yolov2_model.weights"]:::static
        UNC_TYSC["uncompressed/tiny_yolov2_separable_conv_model.weights"]:::static
    end
    Uncompressed --> TFJS

    %% Config & Docs
    Proto["proto/ssd_mobilenet_face_optimized_v2.pbtxt"]:::static
    README["README.md"]:::doc
    CDN --> Proto
    ConsumerApp --> README

    %% Feedback Loop
    TFJS -->|"assembles tensors"| FaceAPI
    FaceAPI -->|"returns inference results"| ConsumerApp

    %% Click Events
    click AGE_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/age_gender_model/"
    click FE_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/face_expression/"
    click FL68_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/face_landmark_68/"
    click FL68T_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/face_landmark_68_tiny/"
    click FR_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/face_recognition/"
    click MTCNN_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/mtcnn/"
    click SSD_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/ssd_mobilenetv1/"
    click TFD_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/tiny_face_detector/"
    click TY_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/tiny_yolov2/"
    click TYSC_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/tiny_yolov2_separable_conv/"
    click UNC_DIR "https://github.com/justadudewhohacks/face-api.js-models/tree/master/uncompressed/"
    click AGE_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/age_gender_model/age_gender_model-weights_manifest.json"
    click FE_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/face_expression/face_expression_model-weights_manifest.json"
    click FL68_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/face_landmark_68/face_landmark_68_model-weights_manifest.json"
    click FL68T_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/face_landmark_68_tiny/face_landmark_68_tiny_model-weights_manifest.json"
    click FR_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/face_recognition/face_recognition_model-weights_manifest.json"
    click MTCNN_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/mtcnn/mtcnn_model-weights_manifest.json"
    click SSD_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/ssd_mobilenetv1/ssd_mobilenetv1_model-weights_manifest.json"
    click TFD_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/tiny_face_detector/tiny_face_detector_model-weights_manifest.json"
    click TY_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/tiny_yolov2/tiny_yolov2_model-weights_manifest.json"
    click TYSC_MAN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/tiny_yolov2_separable_conv/tiny_yolov2_separable_conv_model-weights_manifest.json"
    click AGE_SH1 "https://github.com/justadudewhohacks/face-api.js-models/tree/master/age_gender_model/age_gender_model-shard1"
    click FR_SH1 "https://github.com/justadudewhohacks/face-api.js-models/tree/master/face_recognition/face_recognition_model-shard1"
    click FR_SH2 "https://github.com/justadudewhohacks/face-api.js-models/tree/master/face_recognition/face_recognition_model-shard2"
    click TY_SH1 "https://github.com/justadudewhohacks/face-api.js-models/tree/master/tiny_yolov2/tiny_yolov2_model-shard1"
    click TY_SH2 "https://github.com/justadudewhohacks/face-api.js-models/tree/master/tiny_yolov2/tiny_yolov2_model-shard2"
    click TY_SH3 "https://github.com/justadudewhohacks/face-api.js-models/tree/master/tiny_yolov2/tiny_yolov2_model-shard3"
    click TY_SH4 "https://github.com/justadudewhohacks/face-api.js-models/tree/master/tiny_yolov2/tiny_yolov2_model-shard4"
    click UNC_AG "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/age_gender_model.weights"
    click UNC_FE "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/face_expression_model.weights"
    click UNC_FL68 "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/face_landmark_68_model.weights"
    click UNC_FL68T "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/face_landmark_68_tiny_model.weights"
    click UNC_FR "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/face_recognition_model.weights"
    click UNC_MTCNN "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/mtcnn_model.weights"
    click UNC_SSD "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/ssd_mobilenetv1.weights"
    click UNC_TFD "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/tiny_face_detector_model.weights"
    click UNC_TY "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/tiny_yolov2_model.weights"
    click UNC_TYSC "https://github.com/justadudewhohacks/face-api.js-models/blob/master/uncompressed/tiny_yolov2_separable_conv_model.weights"
    click Proto "https://github.com/justadudewhohacks/face-api.js-models/blob/master/proto/ssd_mobilenet_face_optimized_v2.pbtxt"
    click README "https://github.com/justadudewhohacks/face-api.js-models/blob/master/README.md"

    %% Styles
    classDef static fill:#F9F,stroke:#333,stroke-width:1px
    classDef lib fill:#BBF,stroke:#333,stroke-width:1px
    classDef app fill:#BFB,stroke:#333,stroke-width:1px
    classDef doc fill:#FFB,stroke:#333,stroke-width:1px
```
