# rafribeiro/forensicface architecture

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

- Interactive diagram: https://gitdiagram.com/rafribeiro/forensicface
- Repository: https://github.com/rafribeiro/forensicface

## Overview

forensicface is a Python face-analysis library for forensic examination. The main workflow configures task-specific ONNX models, processes an image through detection, alignment, optional pose/gender/age/quality estimation and embedding extraction, then returns structured face results. It also supports similarity comparison, quality-weighted aggregation, batch processing, video face extraction, and mosaic output. The graph combines README-documented capabilities with sampled implementation evidence; several subsystem links use the documented API because their source was not sampled.

Main entry points: [`src/forensicface/app.py`](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/app.py) (ForensicFace), [`src/forensicface/component_catalog.py`](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/component_catalog.py) (Component Catalog), [`src/forensicface/batch.py`](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/batch.py) (Batch Processing), [`src/forensicface/comparison.py`](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/comparison.py) (Face Comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Application API"]
  node_app["ForensicFace<br/>[app.py]"]
  node_batch["Batch Processing<br/>[batch.py]"]
  node_comparison["Face Comparison<br/>[comparison.py]"]
end

subgraph group_analysis["Face Analysis"]
  node_detect["Face Detection<br/>[scrfd.py]"]
  node_align["Face Alignment"]
  node_attributes["Face Attributes<br/>[landmark.py]"]
  node_quality["Quality Estimation<br/>[quality.py]"]
  node_embedding["Embedding Inference<br/>[recognition.py]"]
  node_geometry["Face Geometry<br/>[geometry.py]"]
end

subgraph group_models["Models And Runtime"]
  node_catalog["Component Catalog"]
  node_components["Component Contracts<br/>[components.py]"]
  node_onnx["ONNX Adapters<br/>[onnx_components.py]"]
  node_store[("Model Store<br/>[model_store.py]")]
  node_runtime["ONNX Runtime"]
end

subgraph group_outputs["Results And Media"]
  node_results["Result Formatting<br/>[results.py]"]
  node_video["Video Processing<br/>[video.py]"]
  node_mosaic["Face Mosaic<br/>[mosaic.py]"]
end

node_user(("Caller"))
node_caller_result["Analysis Results"]

node_user -->|"configures and calls"| node_app
node_app -->|"resolves components"| node_catalog
node_app -->|"locates models"| node_store
node_app -->|"sets providers"| node_runtime
node_catalog -->|"builds contracts"| node_components
node_catalog -->|"selects adapters"| node_onnx
node_app -->|"detects faces"| node_detect
node_app -->|"aligns faces"| node_align
node_app -->|"estimates attributes"| node_attributes
node_app -->|"estimates quality"| node_quality
node_app -->|"extracts embeddings"| node_embedding
node_app -->|"computes geometry"| node_geometry
node_app -->|"formats results"| node_results
node_results -->|"returns results"| node_caller_result
node_user -->|"requests batches"| node_batch
node_batch -->|"processes images"| node_app
node_user -->|"requests comparison"| node_comparison
node_comparison -->|"processes image pair"| node_app
node_user -->|"requests video extraction"| node_video
node_user -->|"requests mosaic"| node_mosaic

click node_app "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/app.py"
click node_catalog "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/component_catalog.py"
click node_components "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/components.py"
click node_onnx "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/onnx_components.py"
click node_store "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/model_store.py"
click node_runtime "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/ort_runtime_setup.py"
click node_detect "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/insightface/scrfd.py"
click node_align "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/aligned_processing.py"
click node_attributes "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/insightface/landmark.py"
click node_quality "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/quality.py"
click node_embedding "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/recognition.py"
click node_batch "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/batch.py"
click node_comparison "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/comparison.py"
click node_results "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/results.py"
click node_video "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/video.py"
click node_mosaic "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/mosaic.py"
click node_geometry "https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/geometry.py"

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_app,node_batch,node_comparison toneBlue
class node_detect,node_align,node_attributes,node_quality,node_embedding,node_geometry toneAmber
class node_catalog,node_components,node_onnx,node_store,node_runtime toneMint
class node_results,node_video,node_mosaic toneRose
class node_user,node_caller_result toneIndigo
```

## Components

### Application API

- [ForensicFace](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/app.py): `src/forensicface/app.py`
- [Batch Processing](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/batch.py): `src/forensicface/batch.py`
- [Face Comparison](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/comparison.py): `src/forensicface/comparison.py`

### Face Analysis

- [Face Detection](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/insightface/scrfd.py): `src/forensicface/insightface/scrfd.py`
- [Face Alignment](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/aligned_processing.py): `src/forensicface/aligned_processing.py`
- [Face Attributes](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/insightface/landmark.py): `src/forensicface/insightface/landmark.py`
- [Quality Estimation](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/quality.py): `src/forensicface/quality.py`
- [Embedding Inference](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/recognition.py): `src/forensicface/recognition.py`
- [Face Geometry](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/geometry.py): `src/forensicface/geometry.py`

### Models And Runtime

- [Component Catalog](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/component_catalog.py): `src/forensicface/component_catalog.py`
- [Component Contracts](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/components.py): `src/forensicface/components.py`
- [ONNX Adapters](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/onnx_components.py): `src/forensicface/onnx_components.py`
- [Model Store](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/model_store.py): `src/forensicface/model_store.py`
- [ONNX Runtime](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/ort_runtime_setup.py): `src/forensicface/ort_runtime_setup.py`

### Results And Media

- [Result Formatting](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/results.py): `src/forensicface/results.py`
- [Video Processing](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/video.py): `src/forensicface/video.py`
- [Face Mosaic](https://github.com/rafribeiro/forensicface/blob/main/src/forensicface/mosaic.py): `src/forensicface/mosaic.py`

### Other components

- **Caller**
- **Analysis Results**

## Connections

- Caller → ForensicFace: configures and calls
- ForensicFace → Component Catalog: resolves components
- ForensicFace → Model Store: locates models
- ForensicFace → ONNX Runtime: sets providers
- Component Catalog → Component Contracts: builds contracts
- Component Catalog → ONNX Adapters: selects adapters
- ForensicFace → Face Detection: detects faces
- ForensicFace → Face Alignment: aligns faces
- ForensicFace → Face Attributes: estimates attributes
- ForensicFace → Quality Estimation: estimates quality
- ForensicFace → Embedding Inference: extracts embeddings
- ForensicFace → Face Geometry: computes geometry
- ForensicFace → Result Formatting: formats results
- Result Formatting → Analysis Results: returns results
- Caller → Batch Processing: requests batches
- Batch Processing → ForensicFace: processes images
- Caller → Face Comparison: requests comparison
- Face Comparison → ForensicFace: processes image pair
- Caller → Video Processing: requests video extraction
- Caller → Face Mosaic: requests mosaic