# projectavsm/digital-facial-recognisation-attendance-system architecture

> Architecture diagram of the GitHub repository projectavsm/digital-facial-recognisation-attendance-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/projectavsm/digital-facial-recognisation-attendance-system
- Repository: https://github.com/projectavsm/digital-facial-recognisation-attendance-system

## Overview

##### Project type + purpose (from README + tree)
This is an **edge-deployed, full-stack IoT/computer-vision “appliance”**:
- Runs on **Raspberry Pi 5** with **Pi Camera Module 3**
- Performs **real-time face detection + embeddings + classification** (MediaPipe + FaceNet + scikit-learn RF)
- Provides a **Flask web dashboard** (templates/static)
- Persists attendance + directory data in **MySQL** (schema.sql)
- Exposes the dashboard securely via **Cloudflare Zero-Trust Tunnel**
- Auto-starts on boot via **systemd** with stability/boot ordering and self-healing

##### bridge.py obtains public URL and emails admin (SMTP)
5. start_system.py launches run_pi.py and/or Flask server (depending on your implementation split)
##### Student identified → DB transaction
- Check presence uniqueness constraint (composite key)
- Insert attendance record if not already present today

##### Camera pipeline is not OpenCV-first
Explicitly label: **rpicam-vid YUV streaming → conversion → inference**, because the README says it’s intentionally bypassing V4L2/Libcamera locks.

##### Dual source of truth for “student directory”
- **MySQL student table(s)**
- **/dataset folder structure**
And show the admin directory “smart portal” scanning **both** (README: dual-lookup mapping Student IDs to physical folders).

##### Remote access is not direct port-forwarding
The “public URL” is through **Cloudflare tunnel**, not NAT. Show Cloudflare as a first-class component, not a footnote.

##### Concrete component list to include (maximally decomposed, based on repo)

- **attendance.service (systemd unit)** (even if file isn’t in repo; README states it)
- **start_system.py** (boot orchestration)
- **bridge.py** (tunnel + URL + email)
- **run_pi.py** (camera loop + server integration)
- **Camera capture: rpicam-vid YUV stream**
- **Frame conversion: YUV → BGR**
- MediaPipe Face Detection
- FaceNet Embedding Generator
- RandomForest Classifier
- StudentID ↔ dataset folder resolver (dual-lookup)
- Flask routes
- SQLAlchemy session/ORM
- Auth/login (templates indicate login.html)
- camera_mark.js (mark attendance flow)
- camera_add_student.js (enrollment flow)
- dashboard.js / admin.js
- **hardware.py** (GPIO/buzzer/LCD)
- **MySQL** (schema.sql, unique constraints)
- **Filesystem dataset (/dataset + symlink to static)**
- **Cloudflare tunnel**
- **SMTP/email provider**
- **Admin browser**

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram A: System Context + Container (C4-ish)
  %% =========================
  subgraph A["A) System Context + Containers (Edge Appliance)"]
    direction TB

    %% --- External Actors / Services ---
    subgraph EXT["External Actors & Services"]
      direction TB
      AdminBrowser["Admin Browser\n(Remote/Local Operator)"]:::external
      Cloudflare["Cloudflare Zero Trust\n(Tunnel + Public URL)"]:::external
      SMTP["SMTP / Email Provider"]:::external
      MySQL[("MySQL Database\n(schema: UNIQUE present once/day)")]:::db
    end

    %% --- Raspberry Pi: Edge Hardware + OS ---
    subgraph HWOS["Raspberry Pi 5: Hardware + OS"]
      direction TB
      Camera["Pi Camera Module 3"]:::hw
      GPIO["GPIO Peripherals\n(Buzzer / LCD)"]:::hw
      DatasetFS["Filesystem Dataset Store\n/dataset + symlink to static"]:::store
      Systemd["systemd\nattendance.service\n(Restart=always,\nafter network-online.target)"]:::ops
    end

    %% --- Raspberry Pi: Application + Logic ---
    subgraph APP["Raspberry Pi 5: Application + Logic"]
      direction TB

      StartSys["start_system.py\nBootstrap/Orchestrator"]:::ops
      Bridge["bridge.py\nTunnel Bridge + URL + Email Notify"]:::ops

      subgraph Runtime["Runtime Services"]
        direction TB
        RunPi["run_pi.py\nMain Execution Loop"]:::ops

        subgraph CV["CV / AI Inference (Realtime)"]
          direction TB
          Rpicam["rpicam-vid\nYUV Stream Capture"]:::cv
          Convert["Frame Conversion\nYUV → BGR"]:::cv
          Model["model.py\nMediaPipe → FaceNet → RF\n+ Dual-lookup resolver"]:::cv
        end

        HardwareCtl["hardware.py\nGPIO/Buzzer/LCD Control"]:::hw
      end

      subgraph WEB["Web Dashboard (Flask)"]
        direction TB
        Flask["app.py\nFlask Routes + SQLAlchemy\n(Auth/Login + Admin UI)"]:::web
        Templates["templates/\nServer-rendered pages"]:::web
        StaticJS["static/js/\nFront-end behaviors"]:::web
        StaticCSS["static/css/\nStyling"]:::web
        StaticImg["static/images/\nAssets"]:::web
      end

      ManualFix["manual_fix.py\nOps/Maintenance Utility"]:::ops
      TestDB["test_db.py\nDB Connectivity Test (Dev)"]:::dev
      Schema["schema.sql\nDDL + Constraints\n(UNIQUE present once/day)"]:::db
      Req["requirements.txt\nPython Dependencies"]:::dev
      ReqPi["requirements-pi.txt\nPi-optimized Dependencies"]:::dev
    end

    %% --- Context/Data Flows (Vertical) ---
    AdminBrowser -->|"HTTP(S) to public URL"| Cloudflare
    Cloudflare -->|"HTTP(S) via Tunnel"| Bridge
    Bridge -->|"Local loopback/proxy to app"| Flask

    Systemd -->|"launches"| StartSys
    StartSys -->|"starts tunnel + get public URL"| Bridge
    Bridge -->|"SMTP: tunnel URL notification"| SMTP

    StartSys -->|"starts runtime loop"| RunPi
    RunPi -->|"opens camera stream"| Rpicam
    Camera -->|"video feed"| Rpicam
    Rpicam -->|"YUV frames"| Convert
    Convert -->|"BGR frames"| Model
    Model -->|"classification result"| HardwareCtl
    HardwareCtl -->|"GPIO signals"| GPIO

    Flask -->|"SQL (SQLAlchemy)"| MySQL
    Model -->|"insert/check attendance\n(duplicate prevention via UNIQUE)"| MySQL

    Flask -->|"read/write images\n(student directory)"| DatasetFS
    Model -->|"dual-lookup:\nStudentID ↔ folder"| DatasetFS

    Schema -->|"defines tables/constraints"| MySQL
    TestDB -->|"connectivity check"| MySQL

    Templates -->|"rendered by"| Flask
    StaticJS -->|"served by"| Flask
    StaticCSS -->|"served by"| Flask
    StaticImg -->|"served by"| Flask

    ManualFix -.->|"repair/stability actions"| StartSys
  end

  %% =========================
  %% Diagram B: Detailed Runtime Sequence (Per Boot + Per Frame)
  %% =========================
  subgraph B["B) Runtime Sequence (Boot + Per-frame Inference)"]
    direction TB

    S1["1. systemd starts service\n(after network-online.target)"]:::ops
    S2["2. start_system.py\nWi-Fi/network readiness checks"]:::ops
    S3["3. bridge.py starts tunnel\nand retrieves public URL"]:::ops
    S4["4. Email public URL\nvia SMTP"]:::external
    S5["5. run_pi.py starts\ncamera + main loop"]:::ops
    S6["6. rpicam-vid streams YUV"]:::cv
    S7["7. Convert YUV → BGR"]:::cv
    S8["8. model.py pipeline\nMediaPipe detect → preprocess → FaceNet embed → RF classify\n+ resolve StudentID ↔ dataset folder"]:::cv
    S9["9. MySQL transaction\nCheck UNIQUE (present once/day)\nInsert attendance if new"]:::db
    S10["10. app.py dashboard\nqueries DB + renders templates/static"]:::web
    S11["11. hardware.py triggers\nbuzzer/LCD feedback"]:::hw

    S1 --> S2 --> S3 --> S4 --> S5
    S5 --> S6 --> S7 --> S8 --> S9 --> S10
    S8 --> S11
    S10 -->|"HTTP(S) via Cloudflare Tunnel"| Cloudflare
  end

  %% =========================
  %% Click Events (from component_mapping)
  %% =========================
  click StartSys "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/start_system.py"
  click RunPi "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/run_pi.py"
  click Flask "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/app.py"
  click Bridge "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/bridge.py"
  click ManualFix "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/manual_fix.py"
  click Model "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/model.py"
  click HardwareCtl "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/hardware.py"
  click Schema "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/schema.sql"
  click TestDB "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/test_db.py"
  click Templates "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/tree/main/templates/"
  click StaticJS "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/tree/main/static/js/"
  click StaticCSS "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/tree/main/static/css/"
  click StaticImg "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/tree/main/static/images/"
  click Req "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/requirements.txt"
  click ReqPi "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/requirements-pi.txt"

  %% Template files
  click TAdd "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/templates/add_student.html"
  click TAdminDir "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/templates/admin_directory.html"
  click TAdminView "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/templates/admin_view.html"
  click TAttendRec "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/templates/attendance_record.html"
  click TIndex "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/templates/index.html"
  click TLogin "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/templates/login.html"
  click TMark "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/templates/mark_attendance.html"

  %% Static JS files
  click JSAdmin "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/static/js/admin.js"
  click JSAdd "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/static/js/camera_add_student.js"
  click JSMark "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/static/js/camera_mark.js"
  click JSDash "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/static/js/dashboard.js"

  %% Static CSS file
  click CSSMain "https://github.com/projectavsm/digital-facial-recognisation-attendance-system/blob/main/static/css/style.css"

  %% Hidden nodes just for click targets (kept minimal & vertical)
  subgraph ClickTargets[" "]
    direction TB
    TAdd["add_student.html"]:::hidden
    TAdminDir["admin_directory.html"]:::hidden
    TAdminView["admin_view.html"]:::hidden
    TAttendRec["attendance_record.html"]:::hidden
    TIndex["index.html"]:::hidden
    TLogin["login.html"]:::hidden
    TMark["mark_attendance.html"]:::hidden

    JSAdmin["admin.js"]:::hidden
    JSAdd["camera_add_student.js"]:::hidden
    JSMark["camera_mark.js"]:::hidden
    JSDash["dashboard.js"]:::hidden

    CSSMain["style.css"]:::hidden
  end

  %% =========================
  %% Styles
  %% =========================
  classDef web fill:#1f6feb,stroke:#0b3d91,color:#ffffff,stroke-width:1.5px
  classDef cv fill:#7c3aed,stroke:#4c1d95,color:#ffffff,stroke-width:1.5px
  classDef db fill:#15803d,stroke:#064e3b,color:#ffffff,stroke-width:1.5px
  classDef store fill:#16a34a,stroke:#065f46,color:#ffffff,stroke-width:1.5px
  classDef ops fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1.5px
  classDef external fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:1.5px
  classDef hw fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1.5px
  classDef dev fill:#a855f7,stroke:#581c87,color:#ffffff,stroke-width:1.5px
  classDef hidden fill:#ffffff,stroke:#ffffff,color:#ffffff,stroke-width:0px

  %% Keep click-target nodes visually absent
  class ClickTargets hidden
```
