# tharushaudana/python-student-attendance-by-face-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/tharushaudana/python-student-attendance-by-face-recognition
- Repository: https://github.com/tharushaudana/python-student-attendance-by-face-recognition

## Overview

##### Project Type and Purpose
- This is a standalone desktop/edge application (not a distributed web service) that uses a webcam to perform real-time face recognition and automatically log daily attendance into Excel sheets.

##### File Structure
- Top‐Level Scripts & Config
- main.py       → application entry point and GUI orchestration
- config.py     → camera index, paths for images, student data, output sheets
- test.py       → basic smoke tests
- Core Functional Modules (“system/” folder)
- capturing.py   → video‐capture pipeline (uses OpenCV)
- simple_facerec.py → face encoding & matching logic (uses face_recognition)
- students.py    → loads student metadata from Excel
- Attendance & Persistence
- mark_attendance.py → decides when to mark a student present
- attendsheet.py     → generates/dumps daily .xlsx attendance files
- Assets & Outputs
- assets/             → input: student_data.xlsx, student_images/
- “Attend Sheets/”    → output: per-day attendance spreadsheets
- Dependencies
- requirements.txt → OpenCV, face_recognition, pandas, openpyxl, GUI libs

##### Extract Architecture Insights from README
- GUI front‐end with real‐time video feed and overlays
- Automated Excel output (one file per day)
- Configurable parameters (camera, file paths)

##### Core Components & Their Interactions
a. Video Capture Module (capturing.py)
- Grabs frames from camera → outputs raw images
b. Face Recognition Engine (simple_facerec.py)
- Pre‐loads student face encodings (from assets/student_images)
c. Student Data Module (students.py)
- Reads student_data.xlsx → builds in-memory mapping of student IDs to names/metadata
d. Attendance Manager (mark_attendance.py)
- Receives face_recognition results + timestamp → ensures one mark per student per day → hands off to attendsheet
e. Excel Writer (attendsheet.py)
- Creates or appends to today’s spreadsheet in “Attend Sheets/”
f. GUI & Main Orchestrator (main.py)
- Initializes modules based on config → starts capture → displays live feed with overlays → listens for quit events

Data Flow:

##### Architectural Patterns & Principles
- Pipeline pattern: capture → process → output
- Single‐process, modular layering (config layer, capture layer, processing layer, persistence layer, presentation layer)
- Separation of concerns: face logic isolated from I/O & UI
- Extensibility point: swap out simple_facerec.py for another recognition engine

##### Technologies & Frameworks
- OpenCV            (video capture & drawing overlays)
- face_recognition  (dlib/Python wrapper for face encoding & matching)
- pandas / openpyxl (Excel I/O)
- tkinter or similar GUI (not explicitly named but implied)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External I/O
    Camera["Camera"]:::io

    %% Configuration Layer
    subgraph "Configuration Layer"
        Config["config.py"]:::config
        Reqs["requirements.txt"]:::config
    end

    %% Application Layer
    subgraph "Application Layer"
        Main["main.py"]:::app
        Test["test.py"]:::app
    end

    %% Processing Layer
    subgraph "Processing Layer"
        Capture["capturing.py\n(OpenCV)"]:::logic
        Recognition["simple_facerec.py\n(face_recognition)"]:::logic
        Students["students.py\n(pandas)"]:::logic
        Mark["mark_attendance.py"]:::logic
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        DataStore1[/"assets/student_data.xlsx"/]:::persist
        DataStore2[[assets/student_images/]]:::persist
        ExcelWriter["attendsheet.py\n(openpyxl)"]:::persist
        OutputSheets[[Attend Sheets/]]:::persist
    end

    %% Data Flow
    Camera -->|"frames"| Capture
    Config --> Main
    Reqs --> Main
    Main -->|"start capture"| Capture
    Capture -->|"frame"| Recognition
    Recognition -->|"face IDs\n+ boxes"| Mark
    Mark -->|"lookup metadata"| Students
    Students --> DataStore1
    Recognition --> DataStore2
    Mark -->|"attendance records"| ExcelWriter
    ExcelWriter --> OutputSheets
    Main -->|"run smoke tests"| Test

    %% Click Events
    click Config "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/config.py"
    click Reqs "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/requirements.txt"
    click Main "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/main.py"
    click Test "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/test.py"
    click Capture "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/system/capturing.py"
    click Recognition "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/system/simple_facerec.py"
    click Students "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/system/students.py"
    click Mark "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/mark_attendance.py"
    click ExcelWriter "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/attendsheet.py"
    click DataStore1 "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/blob/main/assets/student_data.xlsx"
    click DataStore2 "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/tree/main/assets/student_images/"
    click OutputSheets "https://github.com/tharushaudana/python-student-attendance-by-face-recognition/tree/main/Attend Sheets/"

    %% Styles
    classDef io fill:#87CEEB,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef app fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef logic fill:#98FB98,stroke:#000,stroke-width:1px
    classDef persist fill:#FFD700,stroke:#000,stroke-width:1px
```
