# 1997alireza/face-off architecture

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

- Interactive diagram: https://gitdiagram.com/1997alireza/face-off
- Repository: https://github.com/1997alireza/face-off

## Overview

##### Main components
- User Interface and Configuration:
- Files: options.html and options.js.
- Purpose: Provide an interface for users to set parameters (e.g., epsilon values, attack settings) and view results.
- Core Attack Modules:
- Face Detection Attack Module:
– File: face-detector.js
– Associated scripts: perturbation.js and image-tools.js.
- Face Recognition Attack Module:
– File: pgd-impersonator.js
– Likely integrated with faceprivacy.js (or serves as an orchestrator).
- Utility and Reporting:
- Files: tools.js and report-generator.js.
- Purpose: Provide common utilities for image manipulation and generate reports that document how the perturbations have affected output (also indicated by the documentation in docs/).

##### Relationships and interactions
- Input and Preprocessing:
- An image (or dataset from datasets/victims.json) is loaded.
- Utility functions (from image-tools.js and tools.js) preprocess the image.
- Diverging attack pipelines:
- The core controller (possibly faceprivacy.js) decides which attack (detection or recognition) to run based on user input or config parameters.
- In the face detection route, face-detector.js applies the detection model using pre-trained weights (found in models/faceapi-ssdMobilenetV1-weights), and perturbation.js modifies the image based on a loss function that reduces the model’s detection capability.
- Output:
- The resulting perturbed images are stored or visualized.
- A report is generated (with report-generator.js) and documented within the docs/ directory (as evidenced by sample outputs and reports in the docs folder).

##### Architectural design principles
- Modularity: The system is clearly split into separate modules for detection and recognition attacks.
- Reusability: Shared utility functions and tools are kept separate.
- Extensibility: Separate pipelines make it straightforward to integrate additional models or attack types in the future.
- Separation of Concerns: UI (options.html/js) allows configuration while core processing is handled by distinct modules.

##### Relevant technologies
- JavaScript (for both front-end and core logic).
- Pre-trained models (SSD MobileNet V1 for detection and InceptionResnetV1 for recognition) stored under the models directory.
- Adversarial attack algorithms (PGD with momentum) and image augmentation methods.
- Possibly web technologies (HTML/CSS/JS) if this is deployed as a web tool.

– “User Interface & Configuration” for options.html/options.js.
– “Image Input & Preprocessing” for loading images/datasets using tools from image-tools.js.
– “Face Detection Module” (including face-detector.js, perturbation.js, models/faceapi-ssdMobilenetV1-weights).
– “Face Recognition Module” (including pgd-impersonator.js, faceprivacy.js, FaceNet model integration).
– “Utilities & Reporting” (tools.js and report-generator.js).
– From UI to image ingestion,
– From preprocessing to both attack modules,
– And then converge outputs to the reporting module.
– Core processing logic,
– Configuration/Interface elements,
– External models/data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface & Configuration
    subgraph "User Interface & Configuration"
        UI_HTML["Options UI (HTML)"]:::ui
        UI_JS["Options Script (JS)"]:::ui
    end

    %% Image Input & Preprocessing
    IP["Image Input & Preprocessing"]:::process
    DS_Victims["Victims Dataset (victims.json)"]:::data

    %% Face Detection Module Subgraph
    subgraph "Face Detection Module"
        FD_FD["Face Detector (face-detector.js)"]:::core
        FD_PT["Perturbation Module (perturbation.js)"]:::core
        FD_MODEL["SSD Model Weights (faceapi-ssdMobilenetV1-weights)"]:::external
    end

    %% Face Recognition Module Subgraph
    subgraph "Face Recognition Module"
        FR_PGD["PGD Impersonator (pgd-impersonator.js)"]:::core
        FR_FP["Face Privacy Orchestrator (faceprivacy.js)"]:::core
    end

    %% Utilities & Reporting Subgraph
    subgraph "Utilities & Reporting"
        UT_IT["Image Tools (image-tools.js)"]:::util
        UT_TO["Utility Tools (tools.js)"]:::util
        UT_RP["Report Generator (report-generator.js)"]:::util
    end

    %% Output Node
    OUTPUT["Perturbed Images & Report Output"]:::output

    %% Connections
    UI_HTML --> IP
    UI_JS --> IP
    DS_Victims --> IP

    IP --> FD_FD
    IP --> FR_PGD

    FD_FD --> FD_PT
    FD_FD --> FD_MODEL

    FR_PGD --> FR_FP

    FD_PT --> UT_IT
    FR_FP --> UT_IT

    UT_IT --> UT_TO
    UT_TO --> UT_RP
    UT_RP --> OUTPUT

    %% Styles
    classDef ui fill:#ffefd5,stroke:#d2691e,stroke-width:2px;
    classDef process fill:#e6e6fa,stroke:#9370db,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef external fill:#ffcccb,stroke:#8b0000,stroke-width:2px;
    classDef util fill:#98fb98,stroke:#2e8b57,stroke-width:2px;
    classDef data fill:#f5f5dc,stroke:#a0522d,stroke-width:2px;
    classDef output fill:#ffe4e1,stroke:#cd5c5c,stroke-width:2px;

    %% Click Events
    click UI_HTML "https://github.com/1997alireza/face-off/blob/main/options.html"
    click UI_JS "https://github.com/1997alireza/face-off/blob/main/options.js"
    click DS_Victims "https://github.com/1997alireza/face-off/blob/main/datasets/victims.json"
    click FD_FD "https://github.com/1997alireza/face-off/blob/main/face-detector.js"
    click FD_PT "https://github.com/1997alireza/face-off/blob/main/perturbation.js"
    click FD_MODEL "https://github.com/1997alireza/face-off/tree/main/models/faceapi-ssdMobilenetV1-weights"
    click FR_PGD "https://github.com/1997alireza/face-off/blob/main/pgd-impersonator.js"
    click FR_FP "https://github.com/1997alireza/face-off/blob/main/faceprivacy.js"
    click UT_IT "https://github.com/1997alireza/face-off/blob/main/image-tools.js"
    click UT_TO "https://github.com/1997alireza/face-off/blob/main/tools.js"
    click UT_RP "https://github.com/1997alireza/face-off/blob/main/report-generator.js"
```
