# cmusatyalab/openface architecture

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

- Interactive diagram: https://gitdiagram.com/cmusatyalab/openface
- Repository: https://github.com/cmusatyalab/openface

## Overview

##### Project type and purpose
- OpenFace is an open-source face-recognition library and toolkit. It provides:
- A core Python API (`openface/`) wrapping Torch neural nets for feature extraction and face alignment
- Command-line utilities (scripts under top level, `batch-represent/`, `conversion/`, `util/`)
- Training pipelines (Lua/Torch scripts under `training/`)
- Evaluation scripts (`evaluation/`)
- Demos (Python, Lua, and a real-time web demo under `demos/`)
- Model management (`models/`)

##### File structure
- Top-level directories group by functionality:
- `openface/`: core library modules (alignment, data loading, neural-net inference)
- `batch-represent/`, `conversion/`, `util/`: data-processing and utility scripts
- `training/`: Torch training pipelines and configurations
- `evaluation/`: accuracy-evaluation suites on LFW and other benchmarks
- `demos/`: interactive and programmatic demos, including `demos/web` (static assets, JS/CSS, Python websocket server)
- `models/`: pretrained model definitions and scripts to fetch them
- Config files: `setup.py`, `requirements.txt`, Dockerfiles, CI configs, docs in `api-docs/`, `docs/`.

##### Readme insights
- Emphasizes modularity: library + demos + training + evaluation
- Highlights dependencies: Python, Torch, dlib, web stack (WebSocket)

a. Main components
- Core Library Layer (Python modules in `openface/`)
- Model Layer (Torch models in `models/`)
- CLI & Batch Tools Layer (`batch-represent/`, conversion scripts, util scripts)
- Training Layer (Lua/Torch training scripts in `training/`)
- Evaluation Layer (Python/Lua scripts in `evaluation/`)
- Demo Layer
- Local Demos (Python/Lua scripts under `demos/*.py` and `demos/vis-outputs.lua`)
- Web Demo (Front-end: HTML/JS/CSS; Back-end: Python WebSocket server)
- Data Layer (datasets fetched/processed under `data/`)
- External Services/Dependencies:
- dlib (face landmark detection)
- Torch (neural-network runtime)
- Python packages (NumPy, SciPy, Flask or similar for web demo)

b. Relationships & interactions
- CLI/Batch Tools → import Core Library → load models from Model Layer → run inference → write embeddings
- Training Layer → import Core Library modules → consume processed data (Data Layer) → train and export models back to Model Layer
- Evaluation Layer → load Core Library + Model Layer → run benchmarks on datasets → produce accuracy reports
- Local Demos → orchestrate Core Library + Model Layer → show results on images or webcam
- Web Demo Front-end ↔ Web Demo Back-end → uses WebSocket for real-time inference → back-end calls Core Library + Model Layer
- Data Layer is shared by Training, Evaluation, and Conversion scripts

c. Architectural patterns/design principles
- Modular layering: clear separation between core inference library, training, evaluation, and demos
- Reuse of Core Library across tools, demos, training, and evaluation
- Plug-in model definitions: Model Layer uses `.def.lua` files to configure network topology
- Microservice style in web demo: lightweight Python server exposing inference over WebSockets

d. Key technologies/frameworks
- Python 2/3, Torch7 (Lua)
- dlib for facial landmark detection
- WebSocket server (Python) + static front-end (HTML/CSS/JS)
- Docker for containerized builds
- Continuous Integration via Travis, documentation via ReadTheDocs

##### Important note
- Every module group as a component. Don’t omit `conversion/`, `util/`, or `evaluation/`. Each has a role in the overall architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core, Model, Data Layers
    subgraph "Core Library Layer"
        CL["Core Library\n(openface/)"]:::library
    end
    subgraph "Model Layer"
        ML["Model Layer\n(models/)"]:::data
    end
    subgraph "Data Layer"
        DL["Data Layer\n(data/)"]:::data
    end

    %% Tools and Scripts
    subgraph "CLI & Batch Tools Layer"
        BT["Batch & Conversion Tools\n(batch-represent/, conversion/, util/)"]:::tools
    end
    subgraph "Training Layer"
        TR["Training Pipelines\n(training/)"]:::tools
    end
    subgraph "Evaluation Layer"
        EV["Evaluation Scripts\n(evaluation/)"]:::tools
    end

    %% Demo Layer
    subgraph "Demo Layer"
        subgraph "Local Demos"
            LD["Local Demos\n(demos/*.py, vis-outputs.lua)"]:::tools
        end
        subgraph "Web Demo"
            WE_FE["Front-end\n(demos/web/index.html, js/, css/)"]:::frontend
            WE_BE["Back-end Service\n(demos/web/websocket-server.py)"]:::service
        end
    end

    %% External Dependencies
    EXT1["dlib"]:::external
    EXT2["Torch"]:::external
    EXT3["Python Packages"]:::external

    %% Relationships
    BT -->|uses| CL
    BT -->|loads models| ML

    TR -->|imports| CL
    TR -->|reads data| DL
    TR -->|exports models| ML

    EV -->|imports| CL
    EV -->|reads data| DL
    EV -->|loads models| ML

    LD -->|uses| CL
    LD -->|loads models| ML

    WE_FE -- WebSocket --> WE_BE
    WE_BE -->|calls| CL
    WE_BE -->|loads models| ML
    WE_BE -->|uses| EXT1
    WE_BE -->|runs on| EXT2
    WE_BE -->|requires| EXT3

    DL -->|provides data to| CL
    CL -->|consumes models from| ML

    %% Click Events
    click CL "https://github.com/cmusatyalab/openface/tree/master/openface/"
    click ML "https://github.com/cmusatyalab/openface/tree/master/models/"
    click BT "https://github.com/cmusatyalab/openface/tree/master/batch-represent/"
    click TR "https://github.com/cmusatyalab/openface/tree/master/training/"
    click EV "https://github.com/cmusatyalab/openface/tree/master/evaluation/"
    click LD "https://github.com/cmusatyalab/openface/tree/master/demos/"
    click WE_FE "https://github.com/cmusatyalab/openface/blob/master/demos/web/index.html"
    click WE_BE "https://github.com/cmusatyalab/openface/blob/master/demos/web/websocket-server.py"
    click DL "https://github.com/cmusatyalab/openface/tree/master/data/"

    %% Styles
    classDef library fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef tools fill:#d4edda,stroke:#333,stroke-width:1px
    classDef frontend fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef service fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef data fill:#e2e3e5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#f5f5f5,stroke:#999,stroke-dasharray: 2 2,stroke-width:1px
```
