Introduction

UFME (Universal Face Matching Engine) is an open-source biometric face matching engine built for large-scale deployments.

Design targets: ~200 million face gallery, 60 million annual 1:N searches, sub-second end-to-end latency.

What it does

UFME receives a probe image, runs it through a quality-gated biometric pipeline, and searches a sharded FAISS vector index to return ranked candidate matches — or performs enrolment, verification, or deletion against the gallery.

Key capabilities

• 1:N face search against galleries up to 200M entries using sharded FAISS IndexIVFPQ
• Presentation attack detection (PAD) — physical and digital spoofs rejected before matching
• Morphing attack detection (MAD) — blended document photos rejected at enrolment
• ISO/IEC 29794-5 quality gates — configurable accept/reject policy, not hardcoded thresholds
• Hexagonal architecture — any detection model, vector store, or transport layer is swappable

Quick start

# Install Python dependencies
make install

# Download models
make models

# Run tests
make test

# Start the API server
make demo

The REST gateway starts on http://localhost:8080. See the Architecture page for endpoint documentation.

Project layout

src/
├── core/           # Domain logic — zero external dependencies
│   ├── ports/      # Protocol interfaces for all operations
│   ├── domain/     # Pure data types, template operations, scoring
│   └── orchestration/  # Search / Verify / Enrol / Delete orchestrators
├── adapters/
│   ├── inbound/    # REST gateway, gRPC gateway
│   └── outbound/   # FAISS client, ONNX inference, PAD, MAD, OFIQ
├── pipeline/       # Detection → Alignment → Quality → Extraction stages
└── infra/          # Config, logging, health checks
rust/               # Rust hot-path modules (FAISS bindings, SIMD ops)
deploy/             # Dockerfiles, Kubernetes manifests, Helm charts