# dev-mir2011/facial-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/dev-mir2011/facial-recognition
- Repository: https://github.com/dev-mir2011/facial-recognition

## Overview

Facial Recognition is a Flask web application for registering people from face images and identifying submitted images against those registrations. The main workflow is camera capture or upload, API validation and face detection, then registration or ArcFace comparison, with a result returned to the browser. The application also provides login-protected admin views and APIs for registered faces and event logs, plus public health and statistics endpoints. The README documents the model workflow; unsampled templates and route wiring are represented only where supported by the tree or sampled code.

Main entry points: [`routes/api.py`](https://github.com/dev-mir2011/facial-recognition/blob/main/routes/api.py) (API routes), [`templates`](https://github.com/dev-mir2011/facial-recognition/tree/main/templates) (Browser UI), [`app.py`](https://github.com/dev-mir2011/facial-recognition/blob/main/app.py) (Flask app), [`routes/login.py`](https://github.com/dev-mir2011/facial-recognition/blob/main/routes/login.py) (Login routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_browser["Browser UI"]
  node_register_ui["Registration UI<br/>[register.js]"]
  node_recognize_ui["Recognition UI<br/>[recognize.js]"]
  node_home_ui["Home dashboard<br/>[home.js]"]
end

subgraph group_server["Flask application"]
  node_app["Flask app<br/>[app.py]"]
  node_frontend["Page routes<br/>[frontend.py]"]
  node_api["API routes<br/>[api.py]"]
  node_login["Login routes<br/>[login.py]"]
end

subgraph group_recognition["Face processing"]
  node_validation["Upload validation<br/>[validation.py]"]
  node_face_check["Face detection<br/>[recognition.py]"]
  node_matching["Face matching<br/>[recognition.py]"]
  node_file_ops["Image file operations<br/>[files.py]"]
  node_images[("Image files<br/>[api.py]")]
end

subgraph group_admin["Administration and records"]
  node_people[("Registered people<br/>[recognition.py]")]
  node_logs[("Event logs<br/>[log.py]")]
  node_log_helpers["Log access<br/>[log.py]"]
  node_admin_records[("Admin records<br/>[login.py]")]
  node_user_model["Session user<br/>[users.py]"]
end

node_visitor(("Visitor"))
node_deepface{{"DeepFace ArcFace"}}

node_visitor -->|"uses"| node_browser
node_browser -->|"requests pages"| node_frontend
node_app -->|"registers routes"| node_frontend
node_app -->|"registers routes"| node_api
node_app -->|"registers routes"| node_login
node_app -->|"loads session user"| node_user_model
node_frontend -->|"renders templates"| node_browser
node_browser -->|"loads script"| node_register_ui
node_browser -->|"loads script"| node_recognize_ui
node_browser -->|"loads script"| node_home_ui
node_register_ui -->|"posts registration"| node_api
node_recognize_ui -->|"posts image"| node_api
node_home_ui -->|"fetches stats"| node_api
node_api -->|"checks extension"| node_validation
node_api -->|"checks face"| node_face_check
node_api -->|"requests match"| node_matching
node_face_check -->|"extracts faces"| node_deepface
node_matching -->|"verifies images"| node_deepface
node_matching -->|"reads references"| node_people
node_api -->|"writes registrations"| node_people
node_api -->|"saves uploads"| node_images
node_api -->|"cleans images"| node_file_ops
node_api -->|"records events"| node_log_helpers
node_api -->|"gets logs"| node_log_helpers
node_log_helpers -->|"reads and writes"| node_logs
node_api -->|"reads people data"| node_logs
node_login -->|"checks credentials"| node_admin_records
node_login -->|"creates session user"| node_user_model
node_api -->|"resolves admin name"| node_admin_records
node_api -->|"returns API response"| node_browser

click node_browser "https://github.com/dev-mir2011/facial-recognition/tree/main/templates"
click node_register_ui "https://github.com/dev-mir2011/facial-recognition/blob/main/static/js/register.js"
click node_recognize_ui "https://github.com/dev-mir2011/facial-recognition/blob/main/static/js/recognize.js"
click node_home_ui "https://github.com/dev-mir2011/facial-recognition/blob/main/static/js/home.js"
click node_app "https://github.com/dev-mir2011/facial-recognition/blob/main/app.py"
click node_frontend "https://github.com/dev-mir2011/facial-recognition/blob/main/routes/frontend.py"
click node_api "https://github.com/dev-mir2011/facial-recognition/blob/main/routes/api.py"
click node_login "https://github.com/dev-mir2011/facial-recognition/blob/main/routes/login.py"
click node_validation "https://github.com/dev-mir2011/facial-recognition/blob/main/utils/validation.py"
click node_face_check "https://github.com/dev-mir2011/facial-recognition/blob/main/utils/recognition.py"
click node_matching "https://github.com/dev-mir2011/facial-recognition/blob/main/utils/recognition.py"
click node_file_ops "https://github.com/dev-mir2011/facial-recognition/blob/main/utils/files.py"
click node_people "https://github.com/dev-mir2011/facial-recognition/blob/main/utils/recognition.py"
click node_images "https://github.com/dev-mir2011/facial-recognition/blob/main/routes/api.py"
click node_logs "https://github.com/dev-mir2011/facial-recognition/blob/main/utils/log.py"
click node_log_helpers "https://github.com/dev-mir2011/facial-recognition/blob/main/utils/log.py"
click node_admin_records "https://github.com/dev-mir2011/facial-recognition/blob/main/routes/login.py"
click node_user_model "https://github.com/dev-mir2011/facial-recognition/blob/main/utils/users.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_browser,node_register_ui,node_recognize_ui,node_home_ui toneBlue
class node_app,node_frontend,node_api,node_login toneAmber
class node_validation,node_face_check,node_matching,node_file_ops,node_images toneMint
class node_people,node_logs,node_log_helpers,node_admin_records,node_user_model toneRose
class node_visitor,node_deepface toneIndigo
```

## Components

### Web interface

- [Browser UI](https://github.com/dev-mir2011/facial-recognition/tree/main/templates): `templates`
- [Registration UI](https://github.com/dev-mir2011/facial-recognition/blob/main/static/js/register.js): `static/js/register.js`
- [Recognition UI](https://github.com/dev-mir2011/facial-recognition/blob/main/static/js/recognize.js): `static/js/recognize.js`
- [Home dashboard](https://github.com/dev-mir2011/facial-recognition/blob/main/static/js/home.js): `static/js/home.js`

### Flask application

- [Flask app](https://github.com/dev-mir2011/facial-recognition/blob/main/app.py): `app.py`
- [Page routes](https://github.com/dev-mir2011/facial-recognition/blob/main/routes/frontend.py): `routes/frontend.py`
- [API routes](https://github.com/dev-mir2011/facial-recognition/blob/main/routes/api.py): `routes/api.py`
- [Login routes](https://github.com/dev-mir2011/facial-recognition/blob/main/routes/login.py): `routes/login.py`

### Face processing

- [Upload validation](https://github.com/dev-mir2011/facial-recognition/blob/main/utils/validation.py): `utils/validation.py`
- [Face detection](https://github.com/dev-mir2011/facial-recognition/blob/main/utils/recognition.py): `utils/recognition.py`
- [Face matching](https://github.com/dev-mir2011/facial-recognition/blob/main/utils/recognition.py): `utils/recognition.py`
- [Image file operations](https://github.com/dev-mir2011/facial-recognition/blob/main/utils/files.py): `utils/files.py`
- [Image files](https://github.com/dev-mir2011/facial-recognition/blob/main/routes/api.py): `routes/api.py`

### Administration and records

- [Registered people](https://github.com/dev-mir2011/facial-recognition/blob/main/utils/recognition.py): `utils/recognition.py`
- [Event logs](https://github.com/dev-mir2011/facial-recognition/blob/main/utils/log.py): `utils/log.py`
- [Log access](https://github.com/dev-mir2011/facial-recognition/blob/main/utils/log.py): `utils/log.py`
- [Admin records](https://github.com/dev-mir2011/facial-recognition/blob/main/routes/login.py): `routes/login.py`
- [Session user](https://github.com/dev-mir2011/facial-recognition/blob/main/utils/users.py): `utils/users.py`

### Other components

- **Visitor**
- **DeepFace ArcFace**

## Connections

- Visitor → Browser UI: uses
- Browser UI → Page routes: requests pages
- Flask app → Page routes: registers routes
- Flask app → API routes: registers routes
- Flask app → Login routes: registers routes
- Flask app → Session user: loads session user
- Page routes → Browser UI: renders templates
- Browser UI → Registration UI: loads script
- Browser UI → Recognition UI: loads script
- Browser UI → Home dashboard: loads script
- Registration UI → API routes: posts registration
- Recognition UI → API routes: posts image
- Home dashboard → API routes: fetches stats
- API routes → Upload validation: checks extension
- API routes → Face detection: checks face
- API routes → Face matching: requests match
- Face detection → DeepFace ArcFace: extracts faces
- Face matching → DeepFace ArcFace: verifies images
- Face matching → Registered people: reads references
- API routes → Registered people: writes registrations
- API routes → Image files: saves uploads
- API routes → Image file operations: cleans images
- API routes → Log access: records events
- API routes → Log access: gets logs
- Log access → Event logs: reads and writes
- API routes → Event logs: reads people data
- Login routes → Admin records: checks credentials
- Login routes → Session user: creates session user
- API routes → Admin records: resolves admin name
- API routes → Browser UI: returns API response