# danhtran07/ai-enterprise-management-attendance-system architecture

> Architecture diagram of the GitHub repository danhtran07/ai-enterprise-management-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/danhtran07/ai-enterprise-management-attendance-system
- Repository: https://github.com/danhtran07/ai-enterprise-management-attendance-system

## Overview

FaceAttend AI is an employee attendance application: users authenticate, capture a face for recognition and liveness verification, and the backend records attendance; administrators also manage employees, users, shifts, and schedules. The React app calls a FastAPI domain API, which uses PostgreSQL and delegates biometric work to a separate AI service. The AI service combines recognition, liveness, and related analysis. Several backend relationships are visible in indexed source references; links based only on the README architecture are labeled as documented rather than inferred from unsampled code.

Main entry points: [`apps/ai-service/backend/main.py`](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/main.py) (AI service API), [`apps/backend/app/api/routes/attendance.py`](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/attendance.py) (Attendance workflow), [`apps/backend/app/main.py`](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/main.py) (FastAPI application), [`apps/frontend/src/main.tsx`](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/main.tsx) (Web routes and shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web routes and shell<br/>[main.tsx]"]
  node_recognition_ui["Face capture<br/>[App.tsx]"]
  node_dashboard["Attendance dashboard<br/>[Dashboard.tsx]"]
  node_employee_admin["Employee management<br/>[Employees.tsx]"]
  node_http_client["API client<br/>[client.ts]"]
end

subgraph group_api["Attendance API"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication<br/>[auth.py]"]
  node_auth_dependency["Request authorization<br/>[auth.py]"]
  node_attendance_route["Attendance workflow<br/>[attendance.py]"]
  node_employee_routes["Employee endpoints<br/>[employees.py]"]
  node_schedule_routes["Schedules and shifts<br/>[schedules.py]"]
  node_attendance_policy["Attendance policy"]
  node_shift_resolver["Shift resolution<br/>[shift_resolver.py]"]
  node_recognition_logic["Attendance recognition"]
  node_ai_client["AI service client<br/>[ai_client.py]"]
  node_db_session["Database sessions<br/>[database.py]"]
end

subgraph group_ai["Biometric service"]
  node_ai_service["AI service API<br/>[main.py]"]
  node_face_engine["Face recognition"]
  node_liveness_engine["Liveness analysis<br/>[liveness_engine.py]"]
  node_photo_validation["Photo validation<br/>[photo_validator.py]"]
  node_session_manager["Liveness sessions<br/>[session_manager.py]"]
  node_rppg["Heartbeat liveness<br/>[rppg_engine.py]"]
  node_emotion["Emotion analysis<br/>[emotion_engine.py]"]
  node_face_store[("Face embedding store<br/>[face_db.py]")]
end

subgraph group_data["Persistent data"]
  node_database[("PostgreSQL")]
  node_attendance_model["Attendance records<br/>[attendance.py]"]
  node_employee_model["Employee records<br/>[employee.py]"]
  node_user_model["User accounts<br/>[user.py]"]
end

node_employee(("Employee or admin"))

node_employee -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_recognition_ui
node_webapp -->|"routes to"| node_dashboard
node_webapp -->|"routes to"| node_employee_admin
node_recognition_ui -->|"requests through"| node_http_client
node_dashboard -->|"requests through"| node_http_client
node_employee_admin -->|"requests through"| node_http_client
node_http_client -->|"calls REST API"| node_api_app
node_api_app -->|"registers"| node_auth_routes
node_api_app -->|"registers"| node_attendance_route
node_api_app -->|"registers"| node_employee_routes
node_api_app -->|"registers"| node_schedule_routes
node_auth_routes -->|"queries"| node_user_model
node_auth_dependency -->|"loads account"| node_user_model
node_attendance_route -->|"requests recognition"| node_ai_client
node_attendance_route -->|"uses policy"| node_attendance_policy
node_attendance_route -->|"resolves shift"| node_shift_resolver
node_attendance_route -->|"uses recognition"| node_recognition_logic
node_attendance_route -->|"reads and writes"| node_attendance_model
node_employee_routes -->|"enrolls face"| node_ai_client
node_ai_client -->|"calls recognition API"| node_ai_service
node_ai_service -->|"uses"| node_face_engine
node_ai_service -->|"uses"| node_liveness_engine
node_ai_service -->|"uses"| node_photo_validation
node_ai_service -->|"uses"| node_session_manager
node_ai_service -->|"uses"| node_rppg
node_ai_service -->|"uses"| node_emotion
node_ai_service -->|"uses"| node_face_store
node_db_session -->|"connects"| node_database
node_attendance_model -->|"persists in"| node_database
node_employee_model -->|"persists in"| node_database
node_user_model -->|"persists in"| node_database
node_ai_service -.->|"stores embeddings"| node_database

click node_webapp "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/main.tsx"
click node_recognition_ui "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/pages/App.tsx"
click node_dashboard "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/pages/Dashboard.tsx"
click node_employee_admin "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/pages/Employees.tsx"
click node_http_client "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/api/client.ts"
click node_api_app "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/main.py"
click node_auth_routes "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/auth.py"
click node_auth_dependency "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/dependencies/auth.py"
click node_attendance_route "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/attendance.py"
click node_employee_routes "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/employees.py"
click node_schedule_routes "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/schedules.py"
click node_attendance_policy "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/services/attendance_policy.py"
click node_shift_resolver "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/services/shift_resolver.py"
click node_recognition_logic "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/services/attendance_recognition.py"
click node_ai_client "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/services/ai_client.py"
click node_ai_service "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/main.py"
click node_face_engine "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/face_recognition_engine.py"
click node_liveness_engine "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/liveness_engine.py"
click node_photo_validation "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/photo_validator.py"
click node_session_manager "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/session_manager.py"
click node_rppg "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/rppg_engine.py"
click node_emotion "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/emotion_engine.py"
click node_face_store "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/face_db.py"
click node_db_session "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/core/database.py"
click node_attendance_model "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/models/attendance.py"
click node_employee_model "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/models/employee.py"
click node_user_model "https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/models/user.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_recognition_ui,node_dashboard,node_employee_admin,node_http_client toneBlue
class node_api_app,node_auth_routes,node_auth_dependency,node_attendance_route,node_employee_routes,node_schedule_routes,node_attendance_policy,node_shift_resolver,node_recognition_logic,node_ai_client,node_db_session toneAmber
class node_ai_service,node_face_engine,node_liveness_engine,node_photo_validation,node_session_manager,node_rppg,node_emotion,node_face_store toneMint
class node_database,node_attendance_model,node_employee_model,node_user_model toneRose
class node_employee toneIndigo
```

## Components

### Web application

- [Web routes and shell](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/main.tsx): `apps/frontend/src/main.tsx`
- [Face capture](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/pages/App.tsx): `apps/frontend/src/pages/App.tsx`
- [Attendance dashboard](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/pages/Dashboard.tsx): `apps/frontend/src/pages/Dashboard.tsx`
- [Employee management](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/pages/Employees.tsx): `apps/frontend/src/pages/Employees.tsx`
- [API client](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/frontend/src/api/client.ts): `apps/frontend/src/api/client.ts`

### Attendance API

- [FastAPI application](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/main.py): `apps/backend/app/main.py`
- [Authentication](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/auth.py): `apps/backend/app/api/routes/auth.py`
- [Request authorization](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/dependencies/auth.py): `apps/backend/app/api/dependencies/auth.py`
- [Attendance workflow](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/attendance.py): `apps/backend/app/api/routes/attendance.py`
- [Employee endpoints](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/employees.py): `apps/backend/app/api/routes/employees.py`
- [Schedules and shifts](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/api/routes/schedules.py): `apps/backend/app/api/routes/schedules.py`
- [Attendance policy](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/services/attendance_policy.py): `apps/backend/app/services/attendance_policy.py`
- [Shift resolution](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/services/shift_resolver.py): `apps/backend/app/services/shift_resolver.py`
- [Attendance recognition](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/services/attendance_recognition.py): `apps/backend/app/services/attendance_recognition.py`
- [AI service client](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/services/ai_client.py): `apps/backend/app/services/ai_client.py`
- [Database sessions](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/core/database.py): `apps/backend/app/core/database.py`

### Biometric service

- [AI service API](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/main.py): `apps/ai-service/backend/main.py`
- [Face recognition](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/face_recognition_engine.py): `apps/ai-service/backend/face_recognition_engine.py`
- [Liveness analysis](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/liveness_engine.py): `apps/ai-service/backend/liveness_engine.py`
- [Photo validation](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/photo_validator.py): `apps/ai-service/backend/photo_validator.py`
- [Liveness sessions](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/session_manager.py): `apps/ai-service/backend/session_manager.py`
- [Heartbeat liveness](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/rppg_engine.py): `apps/ai-service/backend/rppg_engine.py`
- [Emotion analysis](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/emotion_engine.py): `apps/ai-service/backend/emotion_engine.py`
- [Face embedding store](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/ai-service/backend/face_db.py): `apps/ai-service/backend/face_db.py`

### Persistent data

- **PostgreSQL**
- [Attendance records](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/models/attendance.py): `apps/backend/app/models/attendance.py`
- [Employee records](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/models/employee.py): `apps/backend/app/models/employee.py`
- [User accounts](https://github.com/danhtran07/ai-enterprise-management-attendance-system/blob/main/apps/backend/app/models/user.py): `apps/backend/app/models/user.py`

### Other components

- **Employee or admin**

## Connections

- Employee or admin → Web routes and shell: uses (evidence: `apps/frontend/src/main.tsx`)
- Web routes and shell → Face capture: routes to (evidence: `apps/frontend/src/main.tsx`)
- Web routes and shell → Attendance dashboard: routes to (evidence: `apps/frontend/src/main.tsx`)
- Web routes and shell → Employee management: routes to (evidence: `apps/frontend/src/main.tsx`)
- Face capture → API client: requests through (evidence: `apps/frontend/src/pages/App.tsx`)
- Attendance dashboard → API client: requests through (evidence: `apps/frontend/src/pages/Dashboard.tsx`)
- Employee management → API client: requests through (evidence: `apps/frontend/src/pages/Employees.tsx`)
- API client → FastAPI application: calls REST API (evidence: `README.md`)
- FastAPI application → Authentication: registers (evidence: `apps/backend/app/main.py`)
- FastAPI application → Attendance workflow: registers (evidence: `apps/backend/app/main.py`)
- FastAPI application → Employee endpoints: registers (evidence: `apps/backend/app/main.py`)
- FastAPI application → Schedules and shifts: registers (evidence: `apps/backend/app/main.py`)
- Authentication → User accounts: queries (evidence: `apps/backend/app/api/routes/auth.py`)
- Request authorization → User accounts: loads account (evidence: `apps/backend/app/api/dependencies/auth.py`)
- Attendance workflow → AI service client: requests recognition (evidence: `apps/backend/app/api/routes/attendance.py`)
- Attendance workflow → Attendance policy: uses policy (evidence: `apps/backend/app/api/routes/attendance.py`)
- Attendance workflow → Shift resolution: resolves shift (evidence: `apps/backend/app/api/routes/attendance.py`)
- Attendance workflow → Attendance recognition: uses recognition (evidence: `apps/backend/app/api/routes/attendance.py`)
- Attendance workflow → Attendance records: reads and writes (evidence: `apps/backend/app/api/routes/attendance.py`)
- Employee endpoints → AI service client: enrolls face (evidence: `apps/backend/app/api/routes/employees.py`)
- AI service client → AI service API: calls recognition API (evidence: `apps/backend/app/services/ai_client.py`)
- AI service API → Face recognition: uses (evidence: `apps/ai-service/backend/main.py`)
- AI service API → Liveness analysis: uses (evidence: `apps/ai-service/backend/main.py`)
- AI service API → Photo validation: uses (evidence: `apps/ai-service/backend/main.py`)
- AI service API → Liveness sessions: uses (evidence: `apps/ai-service/backend/main.py`)
- AI service API → Heartbeat liveness: uses (evidence: `apps/ai-service/backend/main.py`)
- AI service API → Emotion analysis: uses (evidence: `apps/ai-service/backend/main.py`)
- AI service API → Face embedding store: uses (evidence: `apps/ai-service/backend/main.py`)
- Database sessions → PostgreSQL: connects (evidence: `README.md`)
- Attendance records → PostgreSQL: persists in (evidence: `README.md`)
- Employee records → PostgreSQL: persists in (evidence: `README.md`)
- User accounts → PostgreSQL: persists in (evidence: `README.md`)
- AI service API → PostgreSQL: stores embeddings
