# nelay04/face-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/nelay04/face-recognition
- Repository: https://github.com/nelay04/face-recognition

## Overview

Face Recognition is a browser-based enrolment and live identification product backed by a FastAPI service. Users enrol a named face from a camera capture or uploaded photo, then send webcam frames for matching; they can also remove identities and inspect service health. The backend decodes images, detects and encodes faces, stores enrolments in SQLite, and compares embeddings to produce recognition results. Relationships for sampled code are grounded in source references; some browser-to-API and documented capabilities rely on the README because frontend/API excerpts are incomplete.

Main entry points: [`backend/app/main.py`](https://github.com/nelay04/face-recognition/blob/main/backend/app/main.py) (App Factory), [`frontend/js/app.js`](https://github.com/nelay04/face-recognition/blob/main/frontend/js/app.js) (UI Controller), [`backend/app/api/v1/router.py`](https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/router.py) (V1 Router), [`backend/app/api/v1/endpoints/faces.py`](https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/endpoints/faces.py) (Enrolment API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser UI"]
  node_webapp["UI Controller<br/>[app.js]"]
  node_webapi["API Client<br/>[api.js]"]
  node_camera["Camera Capture<br/>[camera.js]"]
  node_overlay["Result Overlay<br/>[overlay.js]"]
end

subgraph group_http["HTTP API"]
  node_app["App Factory<br/>[main.py]"]
  node_router["V1 Router<br/>[router.py]"]
  node_faces["Enrolment API<br/>[faces.py]"]
  node_recognize["Recognition API<br/>[recognize.py]"]
  node_health["Health API<br/>[health.py]"]
  node_uploads["Upload Decoder<br/>[uploads.py]"]
  node_deps["Service Dependencies<br/>[deps.py]"]
  node_schemas["Response Models<br/>[common.py]"]
end

subgraph group_recognition["Recognition Services"]
  node_encoder["Face Encoder<br/>[encoder.py]"]
  node_recognizer["Face Matcher<br/>[recognizer.py]"]
  node_gallery["Identity Gallery<br/>[gallery.py]"]
  node_sqlite[("SQLite Gallery")]
  node_image["Image Validation<br/>[image.py]"]
end

subgraph group_platform["Runtime Platform"]
  node_config["Settings<br/>[config.py]"]
  node_device["Device Resolver<br/>[device.py]"]
  node_errors["Error Handling<br/>[exceptions.py]"]
end

node_person(("User"))
node_browser(("Browser"))

node_person -->|"uses"| node_webapp
node_browser -->|"loads UI"| node_webapp
node_webapp -->|"calls"| node_webapi
node_webapp -->|"captures frames"| node_camera
node_webapp -->|"draws results"| node_overlay
node_webapi -->|"posts frames"| node_recognize
node_webapi -.->|"enrols, removes"| node_faces
node_app -->|"mounts routes"| node_router
node_router -->|"registers"| node_faces
node_router -->|"registers"| node_recognize
node_router -->|"registers"| node_health
node_app -->|"initializes"| node_encoder
node_app -->|"initializes"| node_gallery
node_app -->|"initializes"| node_recognizer
node_app -->|"resolves device"| node_device
node_app -->|"loads settings"| node_config
node_app -->|"registers handlers"| node_errors
node_faces -->|"requests services"| node_deps
node_faces -->|"decodes upload"| node_uploads
node_recognize -->|"requests services"| node_deps
node_recognize -->|"decodes upload"| node_uploads
node_health -->|"checks services"| node_deps
node_uploads -->|"decodes image"| node_image
node_encoder -->|"uses image type"| node_image
node_recognizer -->|"reads embeddings"| node_gallery
node_gallery -->|"reads and writes"| node_sqlite
node_errors -->|"renders errors"| node_schemas

click node_webapp "https://github.com/nelay04/face-recognition/blob/main/frontend/js/app.js"
click node_webapi "https://github.com/nelay04/face-recognition/blob/main/frontend/js/api.js"
click node_camera "https://github.com/nelay04/face-recognition/blob/main/frontend/js/camera.js"
click node_overlay "https://github.com/nelay04/face-recognition/blob/main/frontend/js/overlay.js"
click node_app "https://github.com/nelay04/face-recognition/blob/main/backend/app/main.py"
click node_router "https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/router.py"
click node_faces "https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/endpoints/faces.py"
click node_recognize "https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/endpoints/recognize.py"
click node_health "https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/endpoints/health.py"
click node_uploads "https://github.com/nelay04/face-recognition/blob/main/backend/app/api/uploads.py"
click node_deps "https://github.com/nelay04/face-recognition/blob/main/backend/app/api/deps.py"
click node_encoder "https://github.com/nelay04/face-recognition/blob/main/backend/app/services/encoder.py"
click node_recognizer "https://github.com/nelay04/face-recognition/blob/main/backend/app/services/recognizer.py"
click node_gallery "https://github.com/nelay04/face-recognition/blob/main/backend/app/services/gallery.py"
click node_image "https://github.com/nelay04/face-recognition/blob/main/backend/app/utils/image.py"
click node_config "https://github.com/nelay04/face-recognition/blob/main/backend/app/core/config.py"
click node_device "https://github.com/nelay04/face-recognition/blob/main/backend/app/core/device.py"
click node_errors "https://github.com/nelay04/face-recognition/blob/main/backend/app/core/exceptions.py"
click node_schemas "https://github.com/nelay04/face-recognition/blob/main/backend/app/schemas/common.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_webapp,node_webapi,node_camera,node_overlay,node_person,node_browser toneBlue
class node_app,node_router,node_faces,node_recognize,node_health,node_uploads,node_deps,node_schemas toneAmber
class node_encoder,node_recognizer,node_gallery,node_sqlite,node_image toneMint
class node_config,node_device,node_errors toneRose
```

## Components

### Browser UI

- [UI Controller](https://github.com/nelay04/face-recognition/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [API Client](https://github.com/nelay04/face-recognition/blob/main/frontend/js/api.js): `frontend/js/api.js`
- [Camera Capture](https://github.com/nelay04/face-recognition/blob/main/frontend/js/camera.js): `frontend/js/camera.js`
- [Result Overlay](https://github.com/nelay04/face-recognition/blob/main/frontend/js/overlay.js): `frontend/js/overlay.js`

### HTTP API

- [App Factory](https://github.com/nelay04/face-recognition/blob/main/backend/app/main.py): `backend/app/main.py`
- [V1 Router](https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Enrolment API](https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/endpoints/faces.py): `backend/app/api/v1/endpoints/faces.py`
- [Recognition API](https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/endpoints/recognize.py): `backend/app/api/v1/endpoints/recognize.py`
- [Health API](https://github.com/nelay04/face-recognition/blob/main/backend/app/api/v1/endpoints/health.py): `backend/app/api/v1/endpoints/health.py`
- [Upload Decoder](https://github.com/nelay04/face-recognition/blob/main/backend/app/api/uploads.py): `backend/app/api/uploads.py`
- [Service Dependencies](https://github.com/nelay04/face-recognition/blob/main/backend/app/api/deps.py): `backend/app/api/deps.py`
- [Response Models](https://github.com/nelay04/face-recognition/blob/main/backend/app/schemas/common.py): `backend/app/schemas/common.py`

### Recognition Services

- [Face Encoder](https://github.com/nelay04/face-recognition/blob/main/backend/app/services/encoder.py): `backend/app/services/encoder.py`
- [Face Matcher](https://github.com/nelay04/face-recognition/blob/main/backend/app/services/recognizer.py): `backend/app/services/recognizer.py`
- [Identity Gallery](https://github.com/nelay04/face-recognition/blob/main/backend/app/services/gallery.py): `backend/app/services/gallery.py`
- **SQLite Gallery**
- [Image Validation](https://github.com/nelay04/face-recognition/blob/main/backend/app/utils/image.py): `backend/app/utils/image.py`

### Runtime Platform

- [Settings](https://github.com/nelay04/face-recognition/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Device Resolver](https://github.com/nelay04/face-recognition/blob/main/backend/app/core/device.py): `backend/app/core/device.py`
- [Error Handling](https://github.com/nelay04/face-recognition/blob/main/backend/app/core/exceptions.py): `backend/app/core/exceptions.py`

### Other components

- **User**
- **Browser**

## Connections

- User → UI Controller: uses (evidence: `README.md`)
- Browser → UI Controller: loads UI (evidence: `README.md`)
- UI Controller → API Client: calls (evidence: `frontend/js/app.js`)
- UI Controller → Camera Capture: captures frames (evidence: `frontend/js/app.js`)
- UI Controller → Result Overlay: draws results (evidence: `frontend/js/app.js`)
- API Client → Recognition API: posts frames (evidence: `README.md`)
- API Client → Enrolment API: enrols, removes
- App Factory → V1 Router: mounts routes (evidence: `backend/app/main.py`)
- V1 Router → Enrolment API: registers (evidence: `backend/app/api/v1/router.py`)
- V1 Router → Recognition API: registers (evidence: `backend/app/api/v1/router.py`)
- V1 Router → Health API: registers (evidence: `backend/app/api/v1/router.py`)
- App Factory → Face Encoder: initializes (evidence: `backend/app/main.py`)
- App Factory → Identity Gallery: initializes (evidence: `backend/app/main.py`)
- App Factory → Face Matcher: initializes (evidence: `backend/app/main.py`)
- App Factory → Device Resolver: resolves device (evidence: `backend/app/main.py`)
- App Factory → Settings: loads settings (evidence: `backend/app/main.py`)
- App Factory → Error Handling: registers handlers (evidence: `backend/app/main.py`)
- Enrolment API → Service Dependencies: requests services (evidence: `backend/app/api/v1/endpoints/faces.py`)
- Enrolment API → Upload Decoder: decodes upload (evidence: `backend/app/api/v1/endpoints/faces.py`)
- Recognition API → Service Dependencies: requests services (evidence: `backend/app/api/v1/endpoints/recognize.py`)
- Recognition API → Upload Decoder: decodes upload (evidence: `backend/app/api/v1/endpoints/recognize.py`)
- Health API → Service Dependencies: checks services (evidence: `backend/app/api/v1/endpoints/health.py`)
- Upload Decoder → Image Validation: decodes image (evidence: `backend/app/api/uploads.py`)
- Face Encoder → Image Validation: uses image type (evidence: `backend/app/services/encoder.py`)
- Face Matcher → Identity Gallery: reads embeddings (evidence: `backend/app/services/recognizer.py`)
- Identity Gallery → SQLite Gallery: reads and writes (evidence: `backend/app/services/gallery.py`)
- Error Handling → Response Models: renders errors (evidence: `backend/app/core/exceptions.py`)
