# johnnyau19/face-id architecture

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

- Interactive diagram: https://gitdiagram.com/johnnyau19/face-id
- Repository: https://github.com/johnnyau19/face-id

## Overview

##### Project Type and Purpose
- This is a machine-learning–based face verification system (a specialized full-stack project comprising data-prep pipelines, model training/evaluation/inference scripts, and a minimal serving component).
- Purpose: Given two face images, decide if they belong to the same person. Under the hood it uses a Siamese-style neural network (SNN) trained with contrastive loss.

##### File Structure
- Top-level scripts:
- prepare_dataset.py – Splits raw VGGFACE2 into train/val/test folders, removes bad faces, and generates labeled .npy files.
- compute_mean_std.py – Scans train data to compute normalization stats.
- train.py – Loads cached/preprocessed data, trains SNN, saves model checkpoints.
- evaluate.py – Loads a checkpoint and validation set, sweeps thresholds to compute F1/precision/recall/accuracy.
- inference.py – Applies a fixed threshold on test set to compute final metrics.
- server.py – Loads trained model and exposes inference over HTTP (likely via Flask/FastAPI).
- Supporting packages:
- data_manipulate/ – Dataset and preprocessing routines (MTCNN + transform pipeline + caching).
- model/SNN.py – Defines the Siamese CNN encoder + distance layer.
- script/ – Lower-level compute/generate utility scripts.
- utils.py – Shared helper functions (e.g., checkpoint I/O, metric computations).
- Artifacts & config:
- requirements.txt – Python dependencies (PyTorch, facenet-pytorch MTCNN, numpy, flask/fastapi, etc.).
- dataset/*.npy & data/ folders – Data splits & caches.
- mean_std.pt – Stored normalization parameters.

##### README–Driven Architectural Insights
- Three pipeline stages: preprocessing (face detection, cropping, normalization), embedding (SNN encoder), comparison (Euclidean distance + thresholding).
- Caching layer ensures images are preprocessed once per run (speeds up train/eval loops).
- Contrastive loss + L2 regularization drive model optimization.
- Serving component to expose prediction API for pairwise comparisons.

1. Data Ingestion & Splitting
- Raw VGGFACE2 images → prepare_dataset.py → data/train, data/validate, data/test
2. Preprocessing & Caching
- data_manipulate.Dataset + preprocess → MTCNN face crop → transformations → cache on disk (batches/)
- compute_mean_std.py → mean_std.pt
3. Model Training
- train.py: loads cached tensors + mean_std → SNN model (model/SNN.py) → Contrastive Loss + L2 reg → saves checkpoint(s)
4. Model Evaluation
- evaluate.py: loads checkpoint + cached val set → distance computation + threshold sweep → metrics
5. Inference & Testing
- inference.py: loads checkpoint + cached test set → fixed threshold → metrics
6. Serving/API Layer
- server.py: loads best checkpoint + mean_std → REST endpoint receives two images → preprocess → embed → distance → result
Raw Data → prepare_dataset → Split Data → preprocess → Cache → train/evaluate/inference → model checkpoints → server
c. Architectural Patterns & Principles:
- Pipeline pattern: data split → preprocess → model loops → evaluation → deployment
- Modular separation: data manipulation, model definition, training scripts, evaluation, serving
- Caching layer decouples expensive I/O & preprocessing from training/eval loops
- Reproducibility: fixed directory structure and config files
d. Key Technologies & Libraries:
- PyTorch (model, training, checkpointing)
- facenet-pytorch (MTCNN)
- NumPy (.npy datasets)
- Flask/FastAPI (server.py)
- Python standard libraries for CLI parsing (argparse), file I/O

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data Layer"
        Raw["Raw VGGFACE2 Images"]:::external
        Prepare["prepare_dataset.py"]:::script
        click Prepare "https://github.com/johnnyau19/face-id/blob/master/prepare_dataset.py"
        Splits["Data Splits (train/val/test)"]:::artifact
    end

    Raw --> Prepare --> Splits

    subgraph "Preprocessing & Caching"
        Dataset["Dataset Class"]:::data
        click Dataset "https://github.com/johnnyau19/face-id/blob/master/data_manipulate/Dataset.py"
        Preprocess["Transform & MTCNN Pipeline"]:::data
        click Preprocess "https://github.com/johnnyau19/face-id/blob/master/data_manipulate/preprocess.py"
        Cache["Cached Batches"]:::artifact
        ComputeStats["compute_mean_std.py"]:::script
        click ComputeStats "https://github.com/johnnyau19/face-id/blob/master/compute_mean_std.py"
        MeanStd["mean_std.pt"]:::artifact
    end

    Splits --> Dataset --> Preprocess --> Cache
    Splits --> ComputeStats --> MeanStd
    Cache --> Train
    MeanStd --> Train

    subgraph "Model Training"
        Train["train.py"]:::script
        click Train "https://github.com/johnnyau19/face-id/blob/master/train.py"
        Encoder["Siamese Encoder"]:::model
        click Encoder "https://github.com/johnnyau19/face-id/blob/master/model/SNN.py"
        Loss["Contrastive Loss + L2 Reg"]:::model
        Checkpoint["Model Checkpoints"]:::artifact
    end

    Train --> Encoder --> Loss --> Checkpoint

    subgraph "Evaluation & Inference"
        Evaluate["evaluate.py"]:::script
        click Evaluate "https://github.com/johnnyau19/face-id/blob/master/evaluate.py"
        ThresholdSweep["Threshold Sweep"]:::model
        EvalMetrics["Metrics (F1, Precision, Recall)"]:::artifact
        Inference["inference.py"]:::script
        click Inference "https://github.com/johnnyau19/face-id/blob/master/inference.py"
        FixedThresh["Fixed Threshold"]:::model
        TestMetrics["Test Metrics"]:::artifact
    end

    Checkpoint --> Evaluate --> ThresholdSweep --> EvalMetrics
    Checkpoint --> Inference --> FixedThresh --> TestMetrics

    subgraph "Serving/API"
        API["server.py"]:::serve
        click API "https://github.com/johnnyau19/face-id/blob/master/server.py"
        Endpoint["REST Endpoint"]:::serve
    end

    MeanStd --> API
    Checkpoint --> API
    Endpoint -->|Receives two images| Preprocess
    API -->|Returns verification result| Endpoint

    subgraph "Utilities & Config"
        Utils["utils.py"]:::script
        click Utils "https://github.com/johnnyau19/face-id/blob/master/utils.py"
        ComputeScript["compute.py"]:::script
        click ComputeScript "https://github.com/johnnyau19/face-id/blob/master/script/compute.py"
        GenerateScript["generate.py"]:::script
        click GenerateScript "https://github.com/johnnyau19/face-id/blob/master/script/generate.py"
        Requirements["requirements.txt"]:::script
        click Requirements "https://github.com/johnnyau19/face-id/blob/master/requirements.txt"
        Readme["README.md"]:::script
        click Readme "https://github.com/johnnyau19/face-id/blob/master/README.md"
    end

    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef model fill:#90EE90,stroke:#333,stroke-width:1px
    classDef script fill:#FFA500,stroke:#333,stroke-width:1px
    classDef serve fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef artifact fill:#FFD700,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
