# hiepchill/facial_recognition_attendance_system architecture

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

- Interactive diagram: https://gitdiagram.com/hiepchill/facial_recognition_attendance_system
- Repository: https://github.com/hiepchill/facial_recognition_attendance_system

## Overview

##### Main Components
- API Server (FastAPI): This is your core entry point for RESTful endpoints. It includes endpoints for user registration (/register_face), user list (/users), attendance logs (/attendance/{date} and /today_attendance), and live video streaming (/video_feed).
- Face Recognition Engine (InsightFace): Encapsulated in the app/face_recognition.py, this component processes the video frames or still images, performs face embedding, and uses cosine similarity to compare faces.
- Camera Management (OpenCV with Singleton Pattern): Managed in app/camera.py, this module handles the video stream and integrates with the face recognition engine to provide real-time identification.
- Data Persistence:
- SQLite Database: Represented by the file attendance.db and managed by app/database.py, this stores users, face image metadata, and the current attendance status.
- CSV Attendance Logs: Housed in the attendance_logs directory to log check-in and check-out events.
- User and Model Management: Managed with Pydantic models in app/models.py for data validation and consistent API responses.
- Application Configuration: Configurations and settings (file paths, thresholds, etc.) are centralized in app/config.py.
- Dataset Directory: Contains face image datasets for user registration and enrollment.
- Execution Script: The entry point (main.py or run.py) which initializes the FastAPI app and starts the service.

##### Relationships and Interactions
- Clients (mobile/desktop/web or API consumers) make HTTP requests to the FastAPI server.
- API Endpoints interact with:
- The Face Recognition Engine to process images or video frames.
- The Camera Manager for streaming live video.
- The Database module to read/write user and attendance data.
- The Face Recognition Engine sends results (recognized identity, similarity scores) back to the API, which in turn updates both the SQLite database and the CSV log files.
- Configuration settings (such as recognition thresholds and attendance intervals) influence the behavior of both the recognition process and the attendance logic.
- Incoming requests from clients to FastAPI.
- Data flow from the API to recognition and database modules.
- Video stream flow from the camera to the recognition engine.
- Logging flow from the attendance decisions to CSV files.

##### Architectural Patterns and Key Technologies
- Separation of Concerns: Each module (API, recognition, camera handling, database interactions) is isolated to handle its own responsibility.
- Singleton Pattern (in camera.py): Ensures only one instance of the camera resource is active.
- API-Driven Architecture: The FastAPI framework supports clear separation between frontend clients and the backend logic.
- Use of Standard Patterns: The project mimics a service-oriented design where endpoints trigger independent services (e.g., face detection and attendance recording).
- Technology Stack: FastAPI, OpenCV, InsightFace, SQLite, CSV logs, and Pydantic for data validation.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% External Client
    Clients("Clients"):::external

    %% Main System Subgraph
    subgraph "Face Recognition Attendance System"
        API_Server("API Server<br>/register_face, /users, /attendance/{date}, /today_attendance, /video_feed"):::api
        Face_Recognition("Face Recognition Engine<br>(InsightFace, cosine similarity)"):::service
        Camera_Manager("Camera Manager<br>(OpenCV Singleton)"):::service
        Database("SQLite Database<br>(users, face_images, attendance_status)"):::database
        CSV_Logs("CSV Attendance Logs"):::storage
        Pydantic_Models("User & Model Management<br>(Pydantic)"):::models
        App_Config("Application Configuration"):::config
        Dataset_Storage("Dataset Storage"):::storage
    end

    %% Data Flow Connections
    Clients -->|"HTTPRequests"| API_Server
    API_Server -->|"ProcessFace"| Face_Recognition
    API_Server -->|"RequestStream"| Camera_Manager
    Face_Recognition -->|"SendResults"| API_Server
    API_Server -->|"DBInteraction"| Database
    API_Server -->|"LogAttendance"| CSV_Logs
    API_Server -->|"ValidateData"| Pydantic_Models
    Face_Recognition -->|"UseDatasets"| Dataset_Storage
    App_Config -->|"Configures"| API_Server
    App_Config -->|"Configures"| Face_Recognition
    App_Config -->|"Configures"| Camera_Manager

    %% Styles
    classDef external fill:#f9d,stroke:#333,stroke-width:2px;
    classDef api fill:#bbf,stroke:#333,stroke-width:2px;
    classDef service fill:#cfc,stroke:#333,stroke-width:2px;
    classDef database fill:#eee,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef storage fill:#fc9,stroke:#333,stroke-width:2px;
    classDef models fill:#ff9,stroke:#333,stroke-width:2px;
    classDef config fill:#cff,stroke:#333,stroke-width:2px;

    %% Click Events Mapping
    click API_Server "https://github.com/hiepchill/facial_recognition_attendance_system/blob/main/app/run.py"
    click API_Server "https://github.com/hiepchill/facial_recognition_attendance_system/blob/main/main.py"
    click Face_Recognition "https://github.com/hiepchill/facial_recognition_attendance_system/blob/main/app/face_recognition.py"
    click Camera_Manager "https://github.com/hiepchill/facial_recognition_attendance_system/blob/main/app/camera.py"
    click Database "https://github.com/hiepchill/facial_recognition_attendance_system/blob/main/attendance.db"
    click Database "https://github.com/hiepchill/facial_recognition_attendance_system/blob/main/app/database.py"
    click CSV_Logs "https://github.com/hiepchill/facial_recognition_attendance_system/tree/main/attendance_logs"
    click Pydantic_Models "https://github.com/hiepchill/facial_recognition_attendance_system/blob/main/app/models.py"
    click App_Config "https://github.com/hiepchill/facial_recognition_attendance_system/blob/main/app/config.py"
    click Dataset_Storage "https://github.com/hiepchill/facial_recognition_attendance_system/tree/main/dataset"
```
