# turhancan97/intelligent-face-recognition-attendance-system architecture

> Architecture diagram of the GitHub repository turhancan97/intelligent-face-recognition-attendance-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/turhancan97/intelligent-face-recognition-attendance-system
- Repository: https://github.com/turhancan97/intelligent-face-recognition-attendance-system

## Overview

##### Project type and purpose
- This is a full-stack, monolithic Flask web application that automates attendance by performing real-time face recognition.
- The system’s key responsibilities are:
- Serving HTML/CSS/JavaScript pages to students and teachers
- Capturing webcam frames and matching them against a face database
- Persisting user profiles, face embeddings, and attendance records in Firebase Realtime Database and Firebase Storage

##### File structure
- Top level
- app.py – Flask entry point, defines routes and glue logic
- configs/database.yaml – Firebase configuration (URL, storage bucket, service account key path, teacher-login hash)
- requirements.txt – Python dependencies (Flask, OpenCV, firebase-admin, etc.)
- Modules
- detection/face_matching.py – encapsulates face detection, alignment, embedding extraction, and matching logic
- utils/configuration.py – loads YAML, provides config to app and detection module
- Presentation layer
- template/… – Jinja2 HTML templates for home, add_info, attendance, teacher_login, select_class
- static/images – stored face images (mirrors Firebase storage) and UI assets
- Supporting scripts/tests
- generate_password_hash.py – initial teacher-login hash generator
- test/face-detection.py – basic unit/integration test for face detection

##### README for additional insights
- The “System Architecture Design” section describes three logical components:
1. Face Recognition System (OpenCV + dlib + FaceNet embeddings)
2. User Interface (Flask + HTML/CSS/JS)
3. Firebase Database & Storage
- It also shows a high-level interaction flow: capture → detect/recognize → update DB → render UI

a. Main components
- Browser / Webcam (client hardware & front-end)
- Flask Web Server (app.py + templates + static)
- Face Recognition Engine (detection.face_matching)
- Configuration & Utilities (utils.configuration, configs/database.yaml)
- Firebase Services (Realtime Database, Storage, Service Account)
b. Relationships & data flows
1. User opens browser → HTTP GET to Flask → Jinja2 template rendered
2. “Upload / Capture Face” action → browser sends image or triggers webcam stream → Flask route receives image data
3. Flask invokes detection.face_matching:
- Detect & align face, compute embedding
- Compare embedding against stored embeddings (in local folder or fetched from Firebase Storage + Database)
4. On match, Flask writes attendance record (userID + timestamp + class) to Firebase Realtime Database via firebase-admin SDK
5. Teacher login route: Flask verifies hash, queries attendance data from Firebase, and renders attendance.html
c. Architectural patterns & principles
- Layered architecture: Presentation → Business Logic → Data Access
- Single-process monolith (all modules loaded in one Flask app)
- Dependency injection of configuration via utils.configuration
- Clear separation of cross-cutting concerns: face logic isolated in detection/, persistence abstracted by firebase-admin calls
d. Key technologies
- Python 3.8, Flask
- OpenCV, dlib, FaceNet (DeepFace) for face recognition
- Firebase Realtime Database & Firebase Storage
- Jinja2 templates, Werkzeug file-upload handler, Pillow, numpy

##### Essential architectural elements
- Firebase interactions separately for user data vs. attendance records vs. raw image storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Zone
    subgraph "Frontend Zone"
        direction TB
        Browser["Browser / Camera"]:::frontend
        subgraph "Templates"
            direction TB
            Home["home.html"]:::frontend
            AddInfo["add_info.html"]:::frontend
            AttendancePage["attendance.html"]:::frontend
            SelectClass["select_class.html"]:::frontend
            TeacherLogin["teacher_login.html"]:::frontend
        end
        subgraph "Static Assets"
            direction TB
            Images["static/images"]:::frontend
            Recognized["static/recognized"]:::frontend
        end
    end

    %% Backend Zone
    subgraph "Backend Zone"
        direction TB
        FlaskApp["Flask Application\n(app.py)"]:::backend
        ConfigLoader["Configuration Loader\n(utils/configuration.py)"]:::backend
        ConfigFile["Firebase Config\n(configs/database.yaml)"]:::backend
        FaceEngine["Face Recognition Engine\n(detection/face_matching.py)"]:::backend
    end

    %% Scripts & Tests
    subgraph "Scripts & Tests"
        direction TB
        HashScript["generate_password_hash.py"]:::backend
        TestFace["test/face-detection.py"]:::backend
        Requirements["requirements.txt"]:::backend
        Readme["README.md"]:::backend
        License["LICENSE"]:::backend
        DocsImages["docs/images"]:::backend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        DB["Firebase Realtime Database"]:::external
        Storage["Firebase Storage"]:::external
        ServiceAccount["Service Account Key"]:::external
    end

    %% Connections
    Browser -->|GET HTTP| FlaskApp
    FlaskApp -->|Render HTML| Browser
    Browser -->|POST Image Data| FlaskApp

    FlaskApp -->|"load_config()"| ConfigLoader
    ConfigLoader -->|"reads YAML"| ConfigFile

    FlaskApp -->|"detect_and_match()"| FaceEngine
    FaceEngine -->|"uses config"| ConfigLoader
    FaceEngine -->|"reads settings"| ConfigFile

    FaceEngine -->|"fetch embeddings"| Storage
    FaceEngine -->|"fetch profiles"| DB

    FlaskApp -->|"push attendance"| DB
    FlaskApp -->|"query attendance"| DB
    DB -->|"attendance data"| FlaskApp

    %% Click Events
    click FlaskApp "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/app.py"
    click ConfigLoader "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/utils/configuration.py"
    click ConfigFile "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/configs/database.yaml"
    click FaceEngine "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/detection/face_matching.py"
    click Home "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/template/home.html"
    click AddInfo "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/template/add_info.html"
    click AttendancePage "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/template/attendance.html"
    click SelectClass "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/template/select_class.html"
    click TeacherLogin "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/template/teacher_login.html"
    click Images "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/tree/main/static/images"
    click Recognized "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/tree/main/static/recognized"
    click HashScript "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/generate_password_hash.py"
    click TestFace "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/test/face-detection.py"
    click Requirements "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/requirements.txt"
    click Readme "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/blob/main/README.md"
    click License "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/tree/main/LICENSE"
    click DocsImages "https://github.com/turhancan97/intelligent-face-recognition-attendance-system/tree/main/docs/images"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef backend fill:#e3f2fd,stroke:#0d47a1,color:#0d47a1
    classDef external fill:#fff3e0,stroke:#e65100,color:#e65100
```
