# aadhi-shangar/face-recognition-attendance-system architecture

> Architecture diagram of the GitHub repository aadhi-shangar/face-recognition-attendance-system, 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/aadhi-shangar/face-recognition-attendance-system
- Repository: https://github.com/aadhi-shangar/face-recognition-attendance-system

## Overview

This is a browser-based employee attendance system: an administrator manages enrolled users, while employees use a camera kiosk for face recognition and daily check-in. The principal runtime path is browser capture → API recognition → biometric matching → duplicate-aware attendance recording; separate branches provide authentication, employee management, dashboard analytics, and attendance history/export. The diagram uses README architecture statements and source-index references where available; unsampled frontend and router internals are not claimed beyond documented routes and capabilities.

Main entry points: [`frontend/js/api.js`](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/api.js) (HTTP client), [`app/main.py`](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/main.py) (FastAPI application), [`app/services/recognition_service.py`](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/recognition_service.py) (Recognition service), [`app/services/attendance_service.py`](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/attendance_service.py) (Attendance service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser frontend"]
  node_webapi["HTTP client<br/>[api.js]"]
  node_authui["Login UI<br/>[auth.js]"]
  node_userui["Employee directory<br/>[users.js]"]
  node_enrollui["Camera enrollment<br/>[register-user.js]"]
  node_recognitionui["Recognition kiosk<br/>[recognition.js]"]
  node_attendanceui["Attendance history<br/>[attendance.js]"]
  node_dashboardui["Analytics dashboard<br/>[dashboard.js]"]
end

subgraph group_api["API and workflows"]
  node_app["FastAPI application<br/>[main.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_userroutes["Employee routes<br/>[users.py]"]
  node_recognitionroutes["Recognition routes<br/>[recognition.py]"]
  node_attendanceroutes["Attendance routes<br/>[attendance.py]"]
  node_dashboardroutes["Dashboard routes<br/>[dashboard.py]"]
  node_authservice["Authentication service<br/>[auth_service.py]"]
  node_userservice["Employee service<br/>[user_service.py]"]
  node_recognitionservice["Recognition service"]
  node_attendanceservice["Attendance service"]
end

subgraph group_vision["Biometric processing"]
  node_detector["Face detection<br/>[face_detector.py]"]
  node_encoder["Face encoding<br/>[encoder.py]"]
  node_matcher["Embedding matching<br/>[face_recognizer.py]"]
end

subgraph group_data["Persistence and security"]
  node_files["Biometric file storage<br/>[file_handler.py]"]
  node_security["JWT and password security<br/>[security.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
  node_database["Database sessions and schema<br/>[database.py]"]
  node_adminmodel[("Administrator records<br/>[admin.py]")]
  node_usermodel[("Employee records<br/>[user.py]")]
  node_attendancemodel[("Attendance records<br/>[attendance.py]")]
end

node_admin(("Administrator"))
node_employee(("Employee kiosk user"))

node_admin -->|"signs in"| node_authui
node_admin -->|"manages employees"| node_userui
node_employee -->|"presents face"| node_recognitionui
node_authui -->|"sends login"| node_webapi
node_userui -->|"requests CRUD"| node_webapi
node_enrollui -->|"submits image"| node_webapi
node_recognitionui -->|"submits frame"| node_webapi
node_attendanceui -->|"requests history"| node_webapi
node_dashboardui -->|"requests metrics"| node_webapi
node_webapi -->|"sends HTTP"| node_app
node_app -->|"registers routes"| node_authroutes
node_app -->|"registers routes"| node_userroutes
node_app -->|"registers routes"| node_recognitionroutes
node_app -->|"registers routes"| node_attendanceroutes
node_app -->|"registers routes"| node_dashboardroutes
node_authroutes -->|"authenticates"| node_authservice
node_userroutes -->|"delegates CRUD"| node_userservice
node_recognitionroutes -->|"marks check-in"| node_attendanceservice
node_attendanceroutes -->|"queries logs"| node_attendanceservice
node_dashboardroutes -->|"loads metrics"| node_attendanceservice
node_attendanceservice -->|"recognizes frame"| node_recognitionservice
node_recognitionservice -->|"detects faces"| node_detector
node_recognitionservice -->|"encodes face"| node_encoder
node_recognitionservice -->|"compares embeddings"| node_matcher
node_recognitionservice -->|"loads encodings"| node_files
node_userservice -->|"validates enrollment"| node_detector
node_userservice -->|"creates embedding"| node_encoder
node_userservice -->|"stores biometrics"| node_files
node_encoder -->|"uses locations"| node_detector
node_authservice -->|"hashes and signs"| node_security
node_authservice -->|"queries and seeds"| node_adminmodel
node_authroutes -->|"resolves admin"| node_adminmodel
node_authroutes -->|"validates token"| node_security
node_database -->|"reads configuration"| node_settings
node_database -->|"creates schema"| node_adminmodel
node_database -->|"creates schema"| node_usermodel
node_database -->|"creates schema"| node_attendancemodel
node_attendanceservice -->|"queries employee"| node_usermodel
node_attendanceservice -->|"checks and records"| node_attendancemodel
node_recognitionservice -->|"loads gallery users"| node_usermodel

click node_webapi "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/api.js"
click node_authui "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/auth.js"
click node_userui "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/users.js"
click node_enrollui "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/register-user.js"
click node_recognitionui "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/recognition.js"
click node_attendanceui "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/attendance.js"
click node_dashboardui "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/dashboard.js"
click node_app "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/main.py"
click node_authroutes "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/auth.py"
click node_userroutes "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/users.py"
click node_recognitionroutes "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/recognition.py"
click node_attendanceroutes "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/attendance.py"
click node_dashboardroutes "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/dashboard.py"
click node_authservice "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/auth_service.py"
click node_userservice "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/user_service.py"
click node_recognitionservice "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/recognition_service.py"
click node_attendanceservice "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/attendance_service.py"
click node_detector "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/vision/face_detector.py"
click node_encoder "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/vision/encoder.py"
click node_matcher "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/vision/face_recognizer.py"
click node_files "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/utils/file_handler.py"
click node_security "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/utils/security.py"
click node_settings "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/config.py"
click node_database "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/database.py"
click node_adminmodel "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/models/admin.py"
click node_usermodel "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/models/user.py"
click node_attendancemodel "https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/models/attendance.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_webapi,node_authui,node_userui,node_enrollui,node_recognitionui,node_attendanceui,node_dashboardui,node_employee toneBlue
class node_app,node_authroutes,node_userroutes,node_recognitionroutes,node_attendanceroutes,node_dashboardroutes,node_authservice,node_userservice,node_recognitionservice,node_attendanceservice toneAmber
class node_detector,node_encoder,node_matcher toneMint
class node_files,node_security,node_settings,node_database,node_adminmodel,node_usermodel,node_attendancemodel toneRose
class node_admin toneIndigo
```

## Components

### Browser frontend

- [HTTP client](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/api.js): `frontend/js/api.js`
- [Login UI](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/auth.js): `frontend/js/auth.js`
- [Employee directory](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/users.js): `frontend/js/users.js`
- [Camera enrollment](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/register-user.js): `frontend/js/register-user.js`
- [Recognition kiosk](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/recognition.js): `frontend/js/recognition.js`
- [Attendance history](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/attendance.js): `frontend/js/attendance.js`
- [Analytics dashboard](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/frontend/js/dashboard.js): `frontend/js/dashboard.js`

### API and workflows

- [FastAPI application](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/main.py): `app/main.py`
- [Authentication routes](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [Employee routes](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/users.py): `app/routers/users.py`
- [Recognition routes](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/recognition.py): `app/routers/recognition.py`
- [Attendance routes](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/attendance.py): `app/routers/attendance.py`
- [Dashboard routes](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/routers/dashboard.py): `app/routers/dashboard.py`
- [Authentication service](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/auth_service.py): `app/services/auth_service.py`
- [Employee service](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/user_service.py): `app/services/user_service.py`
- [Recognition service](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/recognition_service.py): `app/services/recognition_service.py`
- [Attendance service](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/services/attendance_service.py): `app/services/attendance_service.py`

### Biometric processing

- [Face detection](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/vision/face_detector.py): `app/vision/face_detector.py`
- [Face encoding](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/vision/encoder.py): `app/vision/encoder.py`
- [Embedding matching](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/vision/face_recognizer.py): `app/vision/face_recognizer.py`

### Persistence and security

- [Biometric file storage](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/utils/file_handler.py): `app/utils/file_handler.py`
- [JWT and password security](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/utils/security.py): `app/utils/security.py`
- [Runtime settings](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/config.py): `app/config.py`
- [Database sessions and schema](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/database.py): `app/database.py`
- [Administrator records](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/models/admin.py): `app/models/admin.py`
- [Employee records](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/models/user.py): `app/models/user.py`
- [Attendance records](https://github.com/aadhi-shangar/face-recognition-attendance-system/blob/main/app/models/attendance.py): `app/models/attendance.py`

### Other components

- **Administrator**
- **Employee kiosk user**

## Connections

- Administrator → Login UI: signs in
- Administrator → Employee directory: manages employees
- Employee kiosk user → Recognition kiosk: presents face
- Login UI → HTTP client: sends login
- Employee directory → HTTP client: requests CRUD
- Camera enrollment → HTTP client: submits image
- Recognition kiosk → HTTP client: submits frame
- Attendance history → HTTP client: requests history
- Analytics dashboard → HTTP client: requests metrics
- HTTP client → FastAPI application: sends HTTP
- FastAPI application → Authentication routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Employee routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Recognition routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Attendance routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Dashboard routes: registers routes (evidence: `app/main.py`)
- Authentication routes → Authentication service: authenticates (evidence: `app/routers/auth.py`)
- Employee routes → Employee service: delegates CRUD (evidence: `app/routers/users.py`)
- Recognition routes → Attendance service: marks check-in (evidence: `app/routers/recognition.py`)
- Attendance routes → Attendance service: queries logs (evidence: `app/routers/attendance.py`)
- Dashboard routes → Attendance service: loads metrics (evidence: `app/routers/dashboard.py`)
- Attendance service → Recognition service: recognizes frame (evidence: `app/services/attendance_service.py`)
- Recognition service → Face detection: detects faces (evidence: `app/services/recognition_service.py`)
- Recognition service → Face encoding: encodes face (evidence: `app/services/recognition_service.py`)
- Recognition service → Embedding matching: compares embeddings (evidence: `app/services/recognition_service.py`)
- Recognition service → Biometric file storage: loads encodings (evidence: `app/services/recognition_service.py`)
- Employee service → Face detection: validates enrollment (evidence: `app/services/user_service.py`)
- Employee service → Face encoding: creates embedding (evidence: `app/services/user_service.py`)
- Employee service → Biometric file storage: stores biometrics (evidence: `app/services/user_service.py`)
- Face encoding → Face detection: uses locations (evidence: `app/vision/encoder.py`)
- Authentication service → JWT and password security: hashes and signs (evidence: `app/services/auth_service.py`)
- Authentication service → Administrator records: queries and seeds (evidence: `app/services/auth_service.py`)
- Authentication routes → Administrator records: resolves admin (evidence: `app/routers/auth.py`)
- Authentication routes → JWT and password security: validates token
- Database sessions and schema → Runtime settings: reads configuration (evidence: `app/database.py`)
- Database sessions and schema → Administrator records: creates schema (evidence: `app/database.py`)
- Database sessions and schema → Employee records: creates schema (evidence: `app/database.py`)
- Database sessions and schema → Attendance records: creates schema (evidence: `app/database.py`)
- Attendance service → Employee records: queries employee (evidence: `app/services/attendance_service.py`)
- Attendance service → Attendance records: checks and records (evidence: `app/services/attendance_service.py`)
- Recognition service → Employee records: loads gallery users (evidence: `app/services/recognition_service.py`)
