> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/all-id/architecture-overview.md).

# Architecture Overview

How All ID works and how components interact.

## System architecture

```
┌─────────────┐
│   Client    │
└──────┬──────┘
       │ HTTPS
┌──────▼──────────┐
│ Load Balancer   │
└──────┬──────────┘
       │ HTTP:1302
┌──────▼──────────┐       ┌────────────────┐
│  Peer Service   │──────▶│   Facematch    │
│  • Orchestrates │HTTP   │   • Face match │
│  • Exposes API  │:8080  │   • Anonymize  │
│  • Stores data  │       │   • Extract    │
└──────┬──────────┘       └────────────────┘
       │ MySQL:3306
┌──────▼──────────┐
│  MySQL Database │
│  • Profiles     │
│  • Identifiers  │
│  • Transactions │
└─────────────────┘
```

## Peer Service

The Peer Service is the main application component.

**What it does**:

* Exposes `REST` `API` endpoints (`/profiles`, `/profiles/biometric-validation`)
* Validates incoming requests
* Orchestrates biometric operations
* Stores and retrieves data from MySQL
* Calls Facematch Service for facial recognition
* Can communicate with Certta Router Service for distributed operations
* Returns responses to clients

**Technology**: Node.js application

**Requires**: Facematch Service, MySQL Database

## Facematch Service

The Facematch Service handles facial recognition operations.

**What it does**:

* Receives biometric images from Peer
* Extracts facial features using ML models
* Calculates similarity scores between faces
* Anonymizes biometric images
* Returns feature vectors and scores to Peer

**Technology**: Machine learning service with embedded models

**Requires**: None (self-contained, models included in image)

## Router Service (Certta-hosted)

The Router Service is an orchestration component hosted and managed by Certta (not deployed by you).

**What it does**:

* Routes biometric queries across multiple customer Peer instances
* Enables distributed profile lookups across regions
* Coordinates cross-instance operations for multi-region deployments

**Communication**:

* Your Peer → Certta Router: HTTP requests for distributed queries
* Certta Router → Your Peer: HTTP callbacks with results

**When used**: Multi-region deployments where profile data is distributed across geographic locations

{% hint style="info" %}
You do not deploy or manage the Router Service. It runs on Certta's infrastructure and your Peer Service connects to it when needed for distributed operations.
{% endhint %}

## MySQL Database

Persistent storage for all biometric data.

**What it stores**:

* Biometric profiles (facial features, metadata)
* User identifiers (CPF, name, etc.)
* Transaction history
* Validation results

**Technology**: MySQL 8.0+ or Aurora MySQL 3.10.0+

**Schema**: Provided by Certta during setup

## Data flows

### Profile creation flow

```
1. Client → POST /profiles → Peer Service
2. Peer validates request schema
3. Peer stores identifiers → Database
4. Peer sends biometric image → Facematch
5. Facematch extracts features, anonymizes them (rotates the
   embedding with a private per-peer rotation matrix), and
   returns the rotated embedding vector
6. Peer stores the rotated embedding vector → Database
7. Peer returns success → Client
```

**What gets persisted in the database**:

* **Embedding vector** (bytes) — the rotated, anonymized feature vector. The raw image is never stored.
* **Engine metadata** — model version and image hash used to generate the embedding.
* **Profile/asset metadata** — identifiers and other profile-level data.

Anonymization (rotation) happens inside Facematch before the vector is returned, so Peer only ever handles and persists already-anonymized data.

### Biometric validation flow

```
1. Client → POST /profiles/biometric-validation → Peer Service
2. Peer validates request schema
3. Peer queries existing profile → Database
4. Peer sends comparison request → Facematch
5. Facematch calculates similarity score
6. Facematch returns score and confidence → Peer
7. Peer applies threshold logic (MATCH/NO_MATCH)
8. Peer stores transaction → Database
9. Peer returns validation result → Client
```

### Distributed validation flow (with Certta Router)

```
1. Client → Validation request → Your Peer (Region A)
2. Your Peer checks local database
3. Profile not found locally
4. Your Peer queries → Certta Router Service
5. Certta Router identifies target region
6. Certta Router forwards → Another Peer (Region B)
7. Peer B performs validation
8. Peer B returns result → Certta Router → Your Peer → Client
```

**Embedding rotation across peers**:

Each peer holds its own private orthogonal rotation matrix, so an embedding anonymized for one peer isn't directly comparable against another peer's data. When a query crosses peer boundaries, the Router re-rotates the embedding — reversing the requesting peer's rotation and re-applying the responding peer's rotation — before forwarding it for comparison. This lets Peer instances compare biometric data across the network without any peer ever seeing another peer's private rotation matrix or an unrotated embedding.

{% hint style="info" %}
The Router Service is hosted by Certta. You only need to configure your Peer Service to connect to Certta's Router endpoint.
{% endhint %}

## Service discovery

Your services locate each other using DNS:

```
peer.biometrics.internal:1302
facematch.biometrics.internal:8080
database.biometrics.internal:3306
```

Configure via environment variables (`FACEMATCH_IP`, `MYSQL_IP`, etc.)

For distributed deployments, configure Certta Router endpoint (provided by Certta) in `DS_IP` and `DS_PORT` variables.

## Scaling strategy

**Horizontal scaling** (recommended):

* Add more Peer instances → handle more API requests
* Add more Facematch instances → process more matches in parallel
* Use database read replicas → handle more read queries

**Vertical scaling**:

* Increase Peer resources → faster request processing
* Increase Facematch resources → faster matching (limited benefit, horizontal preferred)
* Increase database resources → faster query processing

## High availability

**Multi-instance deployment**:

* Deploy 2+ Peer instances behind load balancer
* Deploy 2+ Facematch instances
* Use Multi-AZ database

**Health checks**:

* Peer: `GET /health` on port 1302
* Facematch: `GET /health` on port 8080
* Database: MySQL ping

**Automatic failover**:

* Load balancer removes unhealthy Peer instances
* Peer discovers healthy Facematch instances via DNS
* Database fails over to standby (Multi-AZ)

## Security architecture

**Network tiers**:

```
Public Tier     → Load Balancer (HTTPS)
Private Tier    → Peer, Facematch
Database Tier   → MySQL (isolated)
```

**Authentication**:

* Client → Load Balancer: Implement authentication (API keys, OAuth2, etc.)
* Services: Communicate within private network without authentication

**Encryption**:

* Client traffic: HTTPS (TLS)
* Database connections: TLS enabled
* Data at rest: Database encryption enabled


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-api/all-id/architecture-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.