# datamoo-ai/deepface architecture

> Architecture diagram of the GitHub repository datamoo-ai/deepface, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datamoo-ai/deepface
- Repository: https://github.com/datamoo-ai/deepface

## Overview

#### Purpose and Entry Points
DeepFace is a Python facial-recognition and facial-attribute framework. Its public library facade is `deepface/DeepFace.py`, exported through `deepface/__init__.py`. Primary operations are verification, database search, embedding representation, face extraction, demographic analysis, and webcam streaming.

A separate REST deployment path begins at `deepface/api/src/app.py` and `deepface/api/src/api.py`; container startup is defined by `Dockerfile` and `entrypoint.sh`.

#### Public-API Orchestration
`deepface/DeepFace.py` presents static, user-facing operations and delegates to task modules rather than embedding model logic directly:
- verification: `deepface/modules/verification.py`
- identification/search: `deepface/modules/recognition.py`
- embedding generation: `deepface/modules/representation.py`
- attributes: `deepface/modules/demography.py`

This is the principal boundary between callers and the internal pipeline.

#### Shared Face Processing Pipeline
Detection is the common front end for recognition and analysis. `deepface/modules/detection.py` selects a detector, produces face regions/landmarks, aligns faces when enabled, and can invoke liveness checks. `deepface/modules/preprocessing.py` resizes and normalizes detected crops to model-specific input requirements.

Flow: image path/URL/base64/array → image decoding utilities → detection/alignment → padded, normalized face crops → task-specific inference. Core image and filesystem concerns are centralized in `deepface/commons/image_utils.py` and `deepface/commons/folder_utils.py`.

#### Pluggable Model Layer
`deepface/modules/modeling.py` is the model-selection/factory boundary. It supplies task models to callers and isolates supported model implementations:
- recognition model base and implementations: `deepface/models/FacialRecognition.py`, `deepface/models/facial_recognition/ArcFace.py`, `deepface/models/facial_recognition/VGGFace.py`
- detector base and backends: `deepface/models/Detector.py`, `deepface/models/face_detection/RetinaFace.py`, `deepface/models/face_detection/OpenCv.py`
- demographic models: `deepface/models/Demography.py`, `deepface/models/demography/Age.py`

The package wraps external ML ecosystems such as TensorFlow/Keras, OpenCV, Dlib, MTCNN, MediaPipe, RetinaFace, YOLO, and InsightFace-derived models.

#### Recognition and Search Flows
Representation converts each detected face into an embedding. Verification compares two embeddings using configured distance metrics and thresholds. Recognition searches a local image database: it derives/stores embeddings in a pickle cache and compares an input embedding against that cache. These responsibilities reside in `deepface/modules/representation.py`, `deepface/modules/verification.py`, and `deepface/modules/recognition.py`.

Database indexing/vector services are explicitly outside the repository’s core: integrations with vector indexes/databases are expected to be composed by consumers for large-scale search.

#### Attributes, Liveness, and Streaming
Demographic inference applies independent age, gender, race, and emotion predictors to detected faces in `deepface/modules/demography.py`. Optional anti-spoofing uses `deepface/models/spoofing/FasNet.py` during face processing. `deepface/modules/streaming.py` drives webcam frames through detection, recognition, and demographic analysis with temporal focus/display behavior.

#### REST Service and Runtime Boundary
The API layer maps HTTP requests into the same `DeepFace` operations; routing/service separation is under `deepface/api/src/modules/core/routes.py` and `deepface/api/src/modules/core/service.py`. It accepts uploads and image references/encodings, exposing library functionality without a browser UI. The documented production runtime is Gunicorn, optionally packaged in Docker; scripts under `scripts/service.sh` and `scripts/dockerize.sh` operate those deployment modes.

Main entry points: [`deepface/DeepFace.py`](https://github.com/datamoo-ai/deepface/blob/master/deepface/DeepFace.py) (Public facade), [`deepface/modules/representation.py`](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/representation.py) (Representation), [`deepface/modules/detection.py`](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/detection.py) (Detection and alignment), [`deepface/modules/modeling.py`](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/modeling.py) (Model factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["DeepFace library"]
  node_facade["Public facade<br/>Python API<br/>[DeepFace.py]"]
  node_verification["Verification<br/>task module<br/>[verification.py]"]
  node_recognition["Recognition search<br/>task module<br/>[recognition.py]"]
  node_representation["Representation<br/>task module<br/>[representation.py]"]
  node_demography["Demographic analysis<br/>task module<br/>[demography.py]"]
  node_streaming["Webcam streaming<br/>task module<br/>[streaming.py]"]
  node_embedding_cache[("Embedding cache<br/>pickle cache<br/>[recognition.py]")]
end

subgraph group_pipeline["Face pipeline"]
  node_image_utils["Image utilities<br/>shared utility<br/>[image_utils.py]"]
  node_detection["Detection and alignment<br/>pipeline stage<br/>[detection.py]"]
  node_preprocessing["Crop preprocessing<br/>pipeline stage<br/>[preprocessing.py]"]
end

subgraph group_models["Model layer"]
  node_modeling{{"Model factory<br/>selection boundary<br/>[modeling.py]"}}
  node_recognition_models["Recognition models<br/>model family"]
  node_detector_models["Detector backends<br/>model family<br/>[Detector.py]"]
  node_demography_models["Demography models<br/>model family<br/>[Demography.py]"]
  node_spoofing_model["Anti-spoofing model<br/>[FasNet.py]"]
end

subgraph group_service["REST deployment"]
  node_api_app["REST application<br/>API entry point<br/>[app.py]"]
  node_api_routes["HTTP routes<br/>routing layer<br/>[routes.py]"]
  node_api_service["API service<br/>service layer<br/>[service.py]"]
  node_container_runtime["Container startup<br/>deployment runtime"]
end

node_facade -->|"verify"| node_verification
node_facade -->|"find"| node_recognition
node_facade -->|"represent"| node_representation
node_facade -->|"analyze"| node_demography
node_facade -->|"stream"| node_streaming
node_verification -->|"embeddings"| node_representation
node_recognition -->|"query embedding"| node_representation
node_recognition -->|"read/write"| node_embedding_cache
node_representation -->|"decode input"| node_image_utils
node_representation -->|"detect face"| node_detection
node_demography -->|"detect face"| node_detection
node_detection -->|"aligned crops"| node_preprocessing
node_detection -->|"request detector"| node_modeling
node_detection -.->|"optional liveness"| node_spoofing_model
node_representation -->|"request recognizer"| node_modeling
node_demography -->|"request predictors"| node_modeling
node_modeling -->|"select"| node_recognition_models
node_modeling -->|"select"| node_detector_models
node_modeling -->|"select"| node_demography_models
node_streaming -->|"frames"| node_detection
node_streaming -->|"identify"| node_recognition
node_streaming -->|"analyze"| node_demography
node_api_app -->|"registers"| node_api_routes
node_api_routes -->|"dispatch"| node_api_service
node_api_service -->|"library calls"| node_facade
node_container_runtime -->|"serves via Gunicorn"| node_api_app

click node_facade "https://github.com/datamoo-ai/deepface/blob/master/deepface/DeepFace.py"
click node_verification "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/verification.py"
click node_recognition "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/recognition.py"
click node_representation "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/representation.py"
click node_demography "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/demography.py"
click node_streaming "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/streaming.py"
click node_image_utils "https://github.com/datamoo-ai/deepface/blob/master/deepface/commons/image_utils.py"
click node_detection "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/detection.py"
click node_preprocessing "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/preprocessing.py"
click node_modeling "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/modeling.py"
click node_recognition_models "https://github.com/datamoo-ai/deepface/blob/master/deepface/models/FacialRecognition.py"
click node_detector_models "https://github.com/datamoo-ai/deepface/blob/master/deepface/models/Detector.py"
click node_demography_models "https://github.com/datamoo-ai/deepface/blob/master/deepface/models/Demography.py"
click node_spoofing_model "https://github.com/datamoo-ai/deepface/blob/master/deepface/models/spoofing/FasNet.py"
click node_embedding_cache "https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/recognition.py"
click node_api_app "https://github.com/datamoo-ai/deepface/blob/master/deepface/api/src/app.py"
click node_api_routes "https://github.com/datamoo-ai/deepface/blob/master/deepface/api/src/modules/core/routes.py"
click node_api_service "https://github.com/datamoo-ai/deepface/blob/master/deepface/api/src/modules/core/service.py"
click node_container_runtime "https://github.com/datamoo-ai/deepface/blob/master/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_facade,node_verification,node_recognition,node_representation,node_demography,node_streaming,node_embedding_cache toneBlue
class node_image_utils,node_detection,node_preprocessing toneAmber
class node_modeling,node_recognition_models,node_detector_models,node_demography_models,node_spoofing_model toneMint
class node_api_app,node_api_routes,node_api_service,node_container_runtime toneRose
```

## Components

### DeepFace library

- [Public facade](https://github.com/datamoo-ai/deepface/blob/master/deepface/DeepFace.py): Python API · Static user-facing operations. · `deepface/DeepFace.py`
- [Verification](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/verification.py): task module · Compares two face embeddings. · `deepface/modules/verification.py`
- [Recognition search](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/recognition.py): task module · Searches local image databases. · `deepface/modules/recognition.py`
- [Representation](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/representation.py): task module · Generates face embeddings. · `deepface/modules/representation.py`
- [Demographic analysis](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/demography.py): task module · Runs age, gender, race, and emotion inference. · `deepface/modules/demography.py`
- [Webcam streaming](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/streaming.py): task module · Processes webcam frames with temporal display behavior. · `deepface/modules/streaming.py`
- [Embedding cache](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/recognition.py): pickle cache · Stores local database embeddings for search. · `deepface/modules/recognition.py`

### Face pipeline

- [Image utilities](https://github.com/datamoo-ai/deepface/blob/master/deepface/commons/image_utils.py): shared utility · Decodes paths, URLs, base64, and arrays. · `deepface/commons/image_utils.py`
- [Detection and alignment](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/detection.py): pipeline stage · Selects detectors, extracts faces and landmarks, and optionally checks liveness. · `deepface/modules/detection.py`
- [Crop preprocessing](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/preprocessing.py): pipeline stage · Resizes and normalizes crops for model inputs. · `deepface/modules/preprocessing.py`

### Model layer

- [Model factory](https://github.com/datamoo-ai/deepface/blob/master/deepface/modules/modeling.py): selection boundary · Supplies task-specific model implementations. · `deepface/modules/modeling.py`
- [Recognition models](https://github.com/datamoo-ai/deepface/blob/master/deepface/models/FacialRecognition.py): model family · Includes ArcFace and VGGFace implementations. · `deepface/models/FacialRecognition.py`
- [Detector backends](https://github.com/datamoo-ai/deepface/blob/master/deepface/models/Detector.py): model family · Includes RetinaFace and OpenCV backends. · `deepface/models/Detector.py`
- [Demography models](https://github.com/datamoo-ai/deepface/blob/master/deepface/models/Demography.py): model family · Includes independent attribute predictors. · `deepface/models/Demography.py`
- [Anti-spoofing model](https://github.com/datamoo-ai/deepface/blob/master/deepface/models/spoofing/FasNet.py): model · Optional FasNet liveness inference. · `deepface/models/spoofing/FasNet.py`

### REST deployment

- [REST application](https://github.com/datamoo-ai/deepface/blob/master/deepface/api/src/app.py): API entry point · `deepface/api/src/app.py`
- [HTTP routes](https://github.com/datamoo-ai/deepface/blob/master/deepface/api/src/modules/core/routes.py): routing layer · Maps uploads and image references to services. · `deepface/api/src/modules/core/routes.py`
- [API service](https://github.com/datamoo-ai/deepface/blob/master/deepface/api/src/modules/core/service.py): service layer · Invokes the shared DeepFace operations. · `deepface/api/src/modules/core/service.py`
- [Container startup](https://github.com/datamoo-ai/deepface/blob/master/Dockerfile): deployment runtime · Packages and starts the REST service. · `Dockerfile`

## Connections

- Public facade → Verification: verify
- Public facade → Recognition search: find
- Public facade → Representation: represent
- Public facade → Demographic analysis: analyze
- Public facade → Webcam streaming: stream
- Verification → Representation: embeddings
- Recognition search → Representation: query embedding
- Recognition search → Embedding cache: read/write
- Representation → Image utilities: decode input
- Representation → Detection and alignment: detect face
- Demographic analysis → Detection and alignment: detect face
- Detection and alignment → Crop preprocessing: aligned crops
- Detection and alignment → Model factory: request detector
- Detection and alignment → Anti-spoofing model: optional liveness
- Representation → Model factory: request recognizer
- Demographic analysis → Model factory: request predictors
- Model factory → Recognition models: select
- Model factory → Detector backends: select
- Model factory → Demography models: select
- Webcam streaming → Detection and alignment: frames
- Webcam streaming → Recognition search: identify
- Webcam streaming → Demographic analysis: analyze
- REST application → HTTP routes: registers
- HTTP routes → API service: dispatch
- API service → Public facade: library calls
- Container startup → REST application: serves via Gunicorn