# wrishavsett/face-verification-service architecture

> Architecture diagram of the GitHub repository wrishavsett/face-verification-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wrishavsett/face-verification-service
- Repository: https://github.com/wrishavsett/face-verification-service

## Overview

This is a FastAPI face-verification service for examination centres. A caller submits a student ID and webcam image to the verify endpoint; the route decodes the image, retrieves the enrolled reference photo, obtains embeddings for both, applies a similarity threshold, and returns a decision. Enrollment validates a single face before saving the reference. The graph follows the sampled route calls and documented API capabilities; it omits unsampled internals beyond their documented role.

Main entry points: [`app/main.py`](https://github.com/wrishavsett/face-verification-service/blob/main/app/main.py) (FastAPI app), [`app/api/v1/routes/verify.py`](https://github.com/wrishavsett/face-verification-service/blob/main/app/api/v1/routes/verify.py) (Verification route), [`app/services/face_service.py`](https://github.com/wrishavsett/face-verification-service/blob/main/app/services/face_service.py) (Face detection and embeddings), [`app/api/v1/routes/enroll.py`](https://github.com/wrishavsett/face-verification-service/blob/main/app/api/v1/routes/enroll.py) (Enrollment route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entrypoints"]
  node_app["FastAPI app<br/>[main.py]"]
  node_enroll["Enrollment route<br/>[enroll.py]"]
  node_verify["Verification route<br/>[verify.py]"]
end

subgraph group_image["Image processing"]
  node_image_decode["Image decoding<br/>[image_utils.py]"]
end

subgraph group_identity["Face and matching"]
  node_face["Face detection and embeddings<br/>[face_service.py]"]
  node_matching["Similarity decision"]
end

subgraph group_state["Reference storage"]
  node_storage[("Reference photo storage<br/>[storage_service.py]")]
end

subgraph group_runtime["Runtime and contracts"]
  node_settings["Service configuration<br/>[config.py]"]
  node_errors["Error handling<br/>[exceptions.py]"]
  node_responses["Response schemas<br/>[responses.py]"]
  node_requests["Request validation<br/>[requests.py]"]
end

node_caller(("Examination client"))
node_insightface["InsightFace runtime"]

node_caller -->|"sends API requests"| node_app
node_app -->|"routes enrollment"| node_enroll
node_app -->|"routes verification"| node_verify
node_app -->|"initializes model"| node_face
node_enroll -->|"decodes upload"| node_image_decode
node_enroll -->|"checks face count"| node_face
node_enroll -->|"saves reference"| node_storage
node_enroll -->|"returns enrollment schema"| node_responses
node_verify -->|"decodes snapshot"| node_image_decode
node_verify -->|"loads reference"| node_storage
node_verify -->|"embeds both images"| node_face
node_verify -->|"evaluates embeddings"| node_matching
node_verify -->|"returns verification schema"| node_responses
node_face -->|"detects and embeds"| node_insightface
node_face -->|"reads model settings"| node_settings
node_matching -->|"reads threshold"| node_settings
node_storage -->|"reads photo directory"| node_settings
node_storage -->|"decodes stored image"| node_image_decode
node_app -->|"configures API"| node_settings
node_app -->|"maps exceptions"| node_errors
node_image_decode -->|"raises invalid-image errors"| node_errors
node_face -->|"raises face-detection errors"| node_errors
node_storage -->|"raises missing-student error"| node_errors

click node_app "https://github.com/wrishavsett/face-verification-service/blob/main/app/main.py"
click node_enroll "https://github.com/wrishavsett/face-verification-service/blob/main/app/api/v1/routes/enroll.py"
click node_verify "https://github.com/wrishavsett/face-verification-service/blob/main/app/api/v1/routes/verify.py"
click node_image_decode "https://github.com/wrishavsett/face-verification-service/blob/main/app/utils/image_utils.py"
click node_face "https://github.com/wrishavsett/face-verification-service/blob/main/app/services/face_service.py"
click node_matching "https://github.com/wrishavsett/face-verification-service/blob/main/app/services/similarity_service.py"
click node_storage "https://github.com/wrishavsett/face-verification-service/blob/main/app/services/storage_service.py"
click node_settings "https://github.com/wrishavsett/face-verification-service/blob/main/app/core/config.py"
click node_errors "https://github.com/wrishavsett/face-verification-service/blob/main/app/core/exceptions.py"
click node_responses "https://github.com/wrishavsett/face-verification-service/blob/main/app/models/responses.py"
click node_requests "https://github.com/wrishavsett/face-verification-service/blob/main/app/models/requests.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_enroll,node_verify,node_caller toneBlue
class node_image_decode toneAmber
class node_face,node_matching toneMint
class node_storage toneRose
class node_settings,node_errors,node_responses,node_requests,node_insightface toneIndigo
```

## Components

### API entrypoints

- [FastAPI app](https://github.com/wrishavsett/face-verification-service/blob/main/app/main.py): `app/main.py`
- [Enrollment route](https://github.com/wrishavsett/face-verification-service/blob/main/app/api/v1/routes/enroll.py): `app/api/v1/routes/enroll.py`
- [Verification route](https://github.com/wrishavsett/face-verification-service/blob/main/app/api/v1/routes/verify.py): `app/api/v1/routes/verify.py`

### Image processing

- [Image decoding](https://github.com/wrishavsett/face-verification-service/blob/main/app/utils/image_utils.py): `app/utils/image_utils.py`

### Face and matching

- [Face detection and embeddings](https://github.com/wrishavsett/face-verification-service/blob/main/app/services/face_service.py): `app/services/face_service.py`
- [Similarity decision](https://github.com/wrishavsett/face-verification-service/blob/main/app/services/similarity_service.py): `app/services/similarity_service.py`

### Reference storage

- [Reference photo storage](https://github.com/wrishavsett/face-verification-service/blob/main/app/services/storage_service.py): `app/services/storage_service.py`

### Runtime and contracts

- [Service configuration](https://github.com/wrishavsett/face-verification-service/blob/main/app/core/config.py): `app/core/config.py`
- [Error handling](https://github.com/wrishavsett/face-verification-service/blob/main/app/core/exceptions.py): `app/core/exceptions.py`
- [Response schemas](https://github.com/wrishavsett/face-verification-service/blob/main/app/models/responses.py): `app/models/responses.py`
- [Request validation](https://github.com/wrishavsett/face-verification-service/blob/main/app/models/requests.py): `app/models/requests.py`

### Other components

- **Examination client**
- **InsightFace runtime**

## Connections

- Examination client → FastAPI app: sends API requests (evidence: `README.md`)
- FastAPI app → Enrollment route: routes enrollment (evidence: `app/main.py`)
- FastAPI app → Verification route: routes verification (evidence: `app/main.py`)
- FastAPI app → Face detection and embeddings: initializes model (evidence: `app/main.py`)
- Enrollment route → Image decoding: decodes upload (evidence: `app/api/v1/routes/enroll.py`)
- Enrollment route → Face detection and embeddings: checks face count (evidence: `app/api/v1/routes/enroll.py`)
- Enrollment route → Reference photo storage: saves reference (evidence: `app/api/v1/routes/enroll.py`)
- Enrollment route → Response schemas: returns enrollment schema (evidence: `app/api/v1/routes/enroll.py`)
- Verification route → Image decoding: decodes snapshot (evidence: `app/api/v1/routes/verify.py`)
- Verification route → Reference photo storage: loads reference (evidence: `app/api/v1/routes/verify.py`)
- Verification route → Face detection and embeddings: embeds both images (evidence: `app/api/v1/routes/verify.py`)
- Verification route → Similarity decision: evaluates embeddings (evidence: `app/api/v1/routes/verify.py`)
- Verification route → Response schemas: returns verification schema (evidence: `app/api/v1/routes/verify.py`)
- Face detection and embeddings → InsightFace runtime: detects and embeds (evidence: `app/services/face_service.py`)
- Face detection and embeddings → Service configuration: reads model settings (evidence: `app/services/face_service.py`)
- Similarity decision → Service configuration: reads threshold (evidence: `app/services/similarity_service.py`)
- Reference photo storage → Service configuration: reads photo directory (evidence: `app/services/storage_service.py`)
- Reference photo storage → Image decoding: decodes stored image (evidence: `app/services/storage_service.py`)
- FastAPI app → Service configuration: configures API (evidence: `app/main.py`)
- FastAPI app → Error handling: maps exceptions (evidence: `app/main.py`)
- Image decoding → Error handling: raises invalid-image errors (evidence: `app/utils/image_utils.py`)
- Face detection and embeddings → Error handling: raises face-detection errors (evidence: `app/services/face_service.py`)
- Reference photo storage → Error handling: raises missing-student error (evidence: `app/services/storage_service.py`)
