# brian-aldana/sentinel_face_backend architecture

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

- Interactive diagram: https://gitdiagram.com/brian-aldana/sentinel_face_backend
- Repository: https://github.com/brian-aldana/sentinel_face_backend

## Overview

Sentinel Face is a Flask REST backend for biometric access control and administrative management. The main workflow receives recognition frames, checks active employee embeddings, runs active and passive liveness checks plus face matching, then records the access result and any security alert. Separate API branches manage login, employees, users, roles, logs, alerts, and audit history. The graph follows documented and indexed relationships; several controller-to-model links are supported by the SOURCE INDEX rather than fully sampled implementations.

Main entry points: [`db.py`](https://github.com/brian-aldana/sentinel_face_backend/blob/master/db.py) (MariaDB connection pool), [`api/__init__.py`](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/__init__.py) (API factory), [`api/routes`](https://github.com/brian-aldana/sentinel_face_backend/tree/master/api/routes) (Admin routes), [`api/controllers/log_controller.py`](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/log_controller.py) (Recognition and logs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["App entry<br/>[app.py]"]
  node_factory["API factory<br/>[__init__.py]"]
  node_auth_route["Auth routes<br/>[auth_ns.py]"]
  node_employee_route["Employee routes<br/>[employee_ns.py]"]
  node_recognize_route["Recognition route<br/>[recognize_ns.py]"]
  node_log_route["Log routes<br/>[log_ns.py]"]
  node_admin_routes["Admin routes"]
  node_decorators["Admin authorization<br/>[decorators.py]"]
end

subgraph group_biometric["Biometric access"]
  node_log_controller["Recognition and logs<br/>[log_controller.py]"]
  node_face_logic["Face pipeline<br/>[face_logic.py]"]
  node_blink["Blink detection<br/>[blink_detector.py]"]
  node_liveness["Passive liveness<br/>[liveness.py]"]
end

subgraph group_admin["Administration"]
  node_auth_controller["Authentication logic<br/>[auth_controller.py]"]
  node_employee_controller["Employee management"]
  node_usuario_controller["User management"]
  node_role_controller["Role management<br/>[role_controller.py]"]
  node_alert_controller["Alert management"]
  node_audit_controller["Audit queries"]
end

subgraph group_data["Persistence"]
  node_employee_model["Employee records<br/>[employee.py]"]
  node_log_model["Access logs<br/>[log.py]"]
  node_alert_model["Security alerts<br/>[alert.py]"]
  node_audit_model["Audit records<br/>[audit.py]"]
  node_usuario_model["User records<br/>[usuario.py]"]
  node_role_model["Role records<br/>[role.py]"]
  node_db["MariaDB connection pool<br/>[db.py]"]
end

node_client(("API client"))
node_mariadb[("MariaDB")]

node_client -->|"sends requests"| node_app
node_app -->|"creates app"| node_factory
node_factory -->|"registers"| node_auth_route
node_factory -->|"registers"| node_employee_route
node_factory -->|"registers"| node_recognize_route
node_factory -->|"registers"| node_log_route
node_factory -->|"registers"| node_admin_routes
node_auth_route -->|"calls"| node_auth_controller
node_employee_route -->|"calls"| node_employee_controller
node_recognize_route -->|"calls"| node_log_controller
node_log_route -->|"calls"| node_log_controller
node_admin_routes -->|"routes to"| node_usuario_controller
node_admin_routes -->|"routes to"| node_role_controller
node_admin_routes -->|"routes to"| node_alert_controller
node_admin_routes -->|"routes to"| node_audit_controller
node_employee_route -->|"uses"| node_decorators
node_admin_routes -->|"uses"| node_decorators
node_employee_controller -->|"generates embedding"| node_face_logic
node_log_controller -->|"loads active embeddings"| node_employee_model
node_log_controller -->|"processes frames"| node_face_logic
node_log_controller -->|"writes access result"| node_log_model
node_log_controller -->|"creates security alert"| node_alert_model
node_face_logic -->|"checks blink sequence"| node_blink
node_face_logic -->|"checks passive liveness"| node_liveness
node_auth_controller -->|"authenticates users"| node_usuario_model
node_usuario_controller -->|"manages users"| node_usuario_model
node_usuario_controller -->|"records actions"| node_audit_model
node_role_controller -->|"manages roles"| node_role_model
node_role_controller -->|"records actions"| node_audit_model
node_employee_controller -->|"manages employees"| node_employee_model
node_employee_controller -->|"records actions"| node_audit_model
node_alert_controller -->|"manages alerts"| node_alert_model
node_alert_controller -->|"records actions"| node_audit_model
node_audit_controller -->|"queries audit"| node_audit_model
node_employee_model -->|"gets connection"| node_db
node_log_model -->|"gets connection"| node_db
node_alert_model -->|"gets connection"| node_db
node_audit_model -->|"gets connection"| node_db
node_usuario_model -->|"gets connection"| node_db
node_role_model -->|"gets connection"| node_db
node_db -->|"opens pooled connections"| node_mariadb

click node_app "https://github.com/brian-aldana/sentinel_face_backend/blob/master/app.py"
click node_factory "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/__init__.py"
click node_auth_route "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/routes/auth_ns.py"
click node_employee_route "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/routes/employee_ns.py"
click node_recognize_route "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/routes/recognize_ns.py"
click node_log_route "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/routes/log_ns.py"
click node_admin_routes "https://github.com/brian-aldana/sentinel_face_backend/tree/master/api/routes"
click node_auth_controller "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/auth_controller.py"
click node_employee_controller "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/employee_controller.py"
click node_log_controller "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/log_controller.py"
click node_usuario_controller "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/usuario_controller.py"
click node_role_controller "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/role_controller.py"
click node_alert_controller "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/alert_controller.py"
click node_audit_controller "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/audit_controller.py"
click node_decorators "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/decorators.py"
click node_face_logic "https://github.com/brian-aldana/sentinel_face_backend/blob/master/face_logic.py"
click node_blink "https://github.com/brian-aldana/sentinel_face_backend/blob/master/blink_detector.py"
click node_liveness "https://github.com/brian-aldana/sentinel_face_backend/blob/master/liveness.py"
click node_employee_model "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/employee.py"
click node_log_model "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/log.py"
click node_alert_model "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/alert.py"
click node_audit_model "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/audit.py"
click node_usuario_model "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/usuario.py"
click node_role_model "https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/role.py"
click node_db "https://github.com/brian-aldana/sentinel_face_backend/blob/master/db.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_factory,node_auth_route,node_employee_route,node_recognize_route,node_log_route,node_admin_routes,node_decorators,node_client toneBlue
class node_log_controller,node_face_logic,node_blink,node_liveness,node_mariadb toneAmber
class node_auth_controller,node_employee_controller,node_usuario_controller,node_role_controller,node_alert_controller,node_audit_controller toneMint
class node_employee_model,node_log_model,node_alert_model,node_audit_model,node_usuario_model,node_role_model,node_db toneRose
```

## Components

### API and access

- [App entry](https://github.com/brian-aldana/sentinel_face_backend/blob/master/app.py): `app.py`
- [API factory](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/__init__.py): `api/__init__.py`
- [Auth routes](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/routes/auth_ns.py): `api/routes/auth_ns.py`
- [Employee routes](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/routes/employee_ns.py): `api/routes/employee_ns.py`
- [Recognition route](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/routes/recognize_ns.py): `api/routes/recognize_ns.py`
- [Log routes](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/routes/log_ns.py): `api/routes/log_ns.py`
- [Admin routes](https://github.com/brian-aldana/sentinel_face_backend/tree/master/api/routes): `api/routes`
- [Admin authorization](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/decorators.py): `api/decorators.py`

### Biometric access

- [Recognition and logs](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/log_controller.py): `api/controllers/log_controller.py`
- [Face pipeline](https://github.com/brian-aldana/sentinel_face_backend/blob/master/face_logic.py): `face_logic.py`
- [Blink detection](https://github.com/brian-aldana/sentinel_face_backend/blob/master/blink_detector.py): `blink_detector.py`
- [Passive liveness](https://github.com/brian-aldana/sentinel_face_backend/blob/master/liveness.py): `liveness.py`

### Administration

- [Authentication logic](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/auth_controller.py): `api/controllers/auth_controller.py`
- [Employee management](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/employee_controller.py): `api/controllers/employee_controller.py`
- [User management](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/usuario_controller.py): `api/controllers/usuario_controller.py`
- [Role management](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/role_controller.py): `api/controllers/role_controller.py`
- [Alert management](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/alert_controller.py): `api/controllers/alert_controller.py`
- [Audit queries](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/controllers/audit_controller.py): `api/controllers/audit_controller.py`

### Persistence

- [Employee records](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/employee.py): `api/models/employee.py`
- [Access logs](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/log.py): `api/models/log.py`
- [Security alerts](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/alert.py): `api/models/alert.py`
- [Audit records](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/audit.py): `api/models/audit.py`
- [User records](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/usuario.py): `api/models/usuario.py`
- [Role records](https://github.com/brian-aldana/sentinel_face_backend/blob/master/api/models/role.py): `api/models/role.py`
- [MariaDB connection pool](https://github.com/brian-aldana/sentinel_face_backend/blob/master/db.py): `db.py`

### Other components

- **API client**
- **MariaDB**

## Connections

- API client → App entry: sends requests (evidence: `README.md`)
- App entry → API factory: creates app (evidence: `app.py`)
- API factory → Auth routes: registers (evidence: `api/__init__.py`)
- API factory → Employee routes: registers (evidence: `api/__init__.py`)
- API factory → Recognition route: registers (evidence: `api/__init__.py`)
- API factory → Log routes: registers (evidence: `api/__init__.py`)
- API factory → Admin routes: registers (evidence: `api/__init__.py`)
- Auth routes → Authentication logic: calls (evidence: `api/routes/auth_ns.py`)
- Employee routes → Employee management: calls (evidence: `api/routes/employee_ns.py`)
- Recognition route → Recognition and logs: calls (evidence: `api/routes/recognize_ns.py`)
- Log routes → Recognition and logs: calls (evidence: `api/routes/log_ns.py`)
- Admin routes → User management: routes to (evidence: `api/routes/usuario_ns.py`)
- Admin routes → Role management: routes to (evidence: `api/routes/role_ns.py`)
- Admin routes → Alert management: routes to (evidence: `api/routes/alert_ns.py`)
- Admin routes → Audit queries: routes to (evidence: `api/routes/audit_ns.py`)
- Employee routes → Admin authorization: uses (evidence: `api/routes/employee_ns.py`)
- Admin routes → Admin authorization: uses (evidence: `api/routes/usuario_ns.py`)
- Employee management → Face pipeline: generates embedding (evidence: `api/controllers/employee_controller.py`)
- Recognition and logs → Employee records: loads active embeddings (evidence: `api/controllers/log_controller.py`)
- Recognition and logs → Face pipeline: processes frames (evidence: `api/controllers/log_controller.py`)
- Recognition and logs → Access logs: writes access result (evidence: `api/controllers/log_controller.py`)
- Recognition and logs → Security alerts: creates security alert (evidence: `api/controllers/log_controller.py`)
- Face pipeline → Blink detection: checks blink sequence (evidence: `face_logic.py`)
- Face pipeline → Passive liveness: checks passive liveness (evidence: `face_logic.py`)
- Authentication logic → User records: authenticates users (evidence: `api/controllers/auth_controller.py`)
- User management → User records: manages users (evidence: `api/controllers/usuario_controller.py`)
- User management → Audit records: records actions (evidence: `api/controllers/usuario_controller.py`)
- Role management → Role records: manages roles (evidence: `api/controllers/role_controller.py`)
- Role management → Audit records: records actions (evidence: `api/controllers/role_controller.py`)
- Employee management → Employee records: manages employees (evidence: `api/controllers/employee_controller.py`)
- Employee management → Audit records: records actions (evidence: `api/controllers/employee_controller.py`)
- Alert management → Security alerts: manages alerts (evidence: `api/controllers/alert_controller.py`)
- Alert management → Audit records: records actions (evidence: `api/controllers/alert_controller.py`)
- Audit queries → Audit records: queries audit (evidence: `api/controllers/audit_controller.py`)
- Employee records → MariaDB connection pool: gets connection (evidence: `api/models/employee.py`)
- Access logs → MariaDB connection pool: gets connection (evidence: `api/models/log.py`)
- Security alerts → MariaDB connection pool: gets connection (evidence: `api/models/alert.py`)
- Audit records → MariaDB connection pool: gets connection (evidence: `api/models/audit.py`)
- User records → MariaDB connection pool: gets connection (evidence: `api/models/usuario.py`)
- Role records → MariaDB connection pool: gets connection (evidence: `api/models/role.py`)
- MariaDB connection pool → MariaDB: opens pooled connections (evidence: `db.py`)
