# ashish1896/attendance-ai architecture

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

- Interactive diagram: https://gitdiagram.com/ashish1896/attendance-ai
- Repository: https://github.com/ashish1896/attendance-ai

## Overview

1. **What this repository is**
   - SnapClass is a single-application, Streamlit-based attendance system.
   - The app has two primary user roles: **teacher** and **student**, with a landing screen that routes users into the correct portal.

2. **Top-level runtime boundary**
   - `app.py` is the entry point and starts the Streamlit server.
   - Everything else under `src/` is organized as reusable application layers rather than separate services.
   - The app runs as one Python process, but delegates persistence to Supabase/PostgreSQL and computer-vision work to local Python pipelines.

3. **UI composition layer**
   - `src/screens/` contains the main navigation surfaces:
     - `home_screen.py` for role selection
     - `teacher_screen.py` for teacher workflows
     - `student_screen.py` for student workflows
   - `src/ui/base_layout.py` provides the shared page shell and styling wrapper used across screens.
   - `src/assets/` stores static branding and visual assets used by the UI.

4. **Reusable interaction components**
   - `src/components/` holds modular dialogs and controls that are reused by the screens.
   - These include enrollment, photo capture, subject creation, attendance results, QR scan, auto-enroll, and sharing dialogs.
   - `subject_card.py` suggests a reusable display unit for subject summaries or attendance status.
   - `header.py` and `footer.py` are shared chrome elements for consistent page structure.

5. **Browser-side QR scanning boundary**
   - `src/components/qr_scanner/` contains an `index.html` asset, indicating a browser-based QR capture component embedded into the Streamlit UI.
   - This is a distinct front-end boundary: camera access and QR decoding happen in the browser, then results are passed back into the Streamlit flow.

6. **Teacher workflow**
   - The teacher portal is the administrative/control plane.
   - Teachers can create subjects, enroll students, add photos, launch attendance sessions, share subject/session access, and inspect attendance results.
   - The teacher side is the main producer of session state and attendance records in the database.

7. **Student workflow**
   - The student portal is the verification/enrollment plane.
   - Students enroll with photos, then use QR scanning plus face verification to check in.
   - The student screens also surface attendance history and status, so the student side is both a producer of verification events and a consumer of their own records.

8. **Verification pipelines**
   - `src/pipelines/face_pipeline.py` is the AI/vision pipeline for facial verification.
   - Based on the README, it performs image normalization and face matching using Dlib-based embeddings and an SVM classifier.
   - `src/pipelines/qr_pipeline.py` handles QR/session token validation.
   - These pipelines are the core business logic for attendance approval and sit between UI input and database writes.

9. **Data persistence layer**
   - `src/database/config.py` initializes the Supabase client using secrets from Streamlit configuration.
   - `src/database/db.py` is the database abstraction layer for CRUD operations and app-specific queries.
   - Supabase PostgreSQL is the system of record for subjects, enrollments, attendance logs, and session metadata.

10. **Main data flow**
   - Teacher creates a subject/session in the UI.
   - The app stores or updates session/subject records through the database layer.
   - Student scans QR code and submits face data.
   - The QR pipeline validates the session token, the face pipeline verifies identity, and the DB layer records the attendance event if both checks pass.

11. **Operational and security boundary**
   - Secrets are externalized via `.streamlit/secrets.toml`, which keeps Supabase credentials out of source control.
   - The repository’s architecture assumes local runtime state for the Streamlit session and remote persistence in Supabase.
   - The QR/session mechanism is part of the app’s anti-abuse boundary, preventing simple reuse of stale attendance codes.

12. **How to draw the architecture**
   - Model the system as a **single Streamlit application** with three screen entry points.
   - Show a shared UI component layer feeding both teacher and student portals.
   - Place the **QR HTML scanner** as a browser-side subcomponent.
   - Place the **face and QR pipelines** as local processing services inside the app runtime.
   - Show **Supabase/PostgreSQL** as the external persistence backend accessed through the database config/DB abstraction layer.

Main entry points: [`src/screens/student_screen.py`](https://github.com/ashish1896/attendance-ai/blob/main/src/screens/student_screen.py) (Student), [`src/database/db.py`](https://github.com/ashish1896/attendance-ai/blob/main/src/database/db.py) (DB layer), [`src/screens/teacher_screen.py`](https://github.com/ashish1896/attendance-ai/blob/main/src/screens/teacher_screen.py) (Teacher), [`src/ui/base_layout.py`](https://github.com/ashish1896/attendance-ai/blob/main/src/ui/base_layout.py) (Base layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app["App entry<br/>streamlit bootstrap<br/>[app.py]"]
end

subgraph group_ui["UI"]
  node_home_screen["Home<br/>landing screen<br/>[home_screen.py]"]
  node_teacher_screen["Teacher<br/>admin portal<br/>[teacher_screen.py]"]
  node_student_screen["Student<br/>[student_screen.py]"]
  node_base_layout["Base layout<br/>shared shell<br/>[base_layout.py]"]
  node_header["Header<br/>chrome component<br/>[header.py]"]
  node_footer["Footer<br/>chrome component<br/>[footer.py]"]
  node_subject_card["Subject card<br/>reusable card<br/>[subject_card.py]"]
  node_dialogs["Dialogs<br/>workflow modals<br/>[dialog_enroll.py]"]
  node_assets["Assets<br/>static media"]
end

subgraph group_browser["Browser"]
  node_qr_scanner["QR scanner<br/>browser widget<br/>[index.html]"]
end

subgraph group_logic["Logic"]
  node_face_pipeline["Face verify<br/>vision pipeline<br/>[face_pipeline.py]"]
  node_qr_pipeline["QR validate<br/>session pipeline<br/>[qr_pipeline.py]"]
end

subgraph group_data["Data"]
  node_db_config["DB config<br/>supabase setup<br/>[config.py]"]
  node_db[("DB layer<br/>persistence api<br/>[db.py]")]
end

node_app -->|"routes to"| node_home_screen
node_app -->|"uses shell"| node_base_layout
node_base_layout -->|"includes"| node_header
node_base_layout -->|"includes"| node_footer
node_base_layout -->|"uses"| node_assets
node_home_screen -->|"enters"| node_teacher_screen
node_home_screen -->|"enters"| node_student_screen
node_teacher_screen -->|"invokes"| node_dialogs
node_teacher_screen -->|"shows"| node_subject_card
node_student_screen -->|"invokes"| node_dialogs
node_student_screen -->|"embeds"| node_qr_scanner
node_teacher_screen -->|"issues sessions"| node_qr_pipeline
node_student_screen -->|"validates token"| node_qr_pipeline
node_student_screen -->|"verifies identity"| node_face_pipeline
node_teacher_screen -->|"writes records"| node_db
node_student_screen -->|"reads writes"| node_db
node_db -->|"initializes via"| node_db_config
node_db_config -->|"connects"| node_db
node_qr_pipeline -->|"checks state"| node_db
node_face_pipeline -->|"persists outcome"| node_db

click node_app "https://github.com/ashish1896/attendance-ai/blob/main/app.py"
click node_home_screen "https://github.com/ashish1896/attendance-ai/blob/main/src/screens/home_screen.py"
click node_teacher_screen "https://github.com/ashish1896/attendance-ai/blob/main/src/screens/teacher_screen.py"
click node_student_screen "https://github.com/ashish1896/attendance-ai/blob/main/src/screens/student_screen.py"
click node_base_layout "https://github.com/ashish1896/attendance-ai/blob/main/src/ui/base_layout.py"
click node_header "https://github.com/ashish1896/attendance-ai/blob/main/src/components/header.py"
click node_footer "https://github.com/ashish1896/attendance-ai/blob/main/src/components/footer.py"
click node_subject_card "https://github.com/ashish1896/attendance-ai/blob/main/src/components/subject_card.py"
click node_dialogs "https://github.com/ashish1896/attendance-ai/blob/main/src/components/dialog_enroll.py"
click node_qr_scanner "https://github.com/ashish1896/attendance-ai/blob/main/src/components/qr_scanner/index.html"
click node_face_pipeline "https://github.com/ashish1896/attendance-ai/blob/main/src/pipelines/face_pipeline.py"
click node_qr_pipeline "https://github.com/ashish1896/attendance-ai/blob/main/src/pipelines/qr_pipeline.py"
click node_db_config "https://github.com/ashish1896/attendance-ai/blob/main/src/database/config.py"
click node_db "https://github.com/ashish1896/attendance-ai/blob/main/src/database/db.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_app toneBlue
class node_home_screen,node_teacher_screen,node_student_screen,node_base_layout,node_header,node_footer,node_subject_card,node_dialogs,node_assets toneAmber
class node_qr_scanner toneMint
class node_face_pipeline,node_qr_pipeline toneRose
class node_db_config,node_db toneIndigo
```

## Components

### Runtime

Streamlit application entry and process boundary

- [App entry](https://github.com/ashish1896/attendance-ai/blob/main/app.py): streamlit bootstrap · Starts the single Streamlit process and routes into the app shell · `app.py`

### UI

Screens, shared layout, and reusable components

- [Home](https://github.com/ashish1896/attendance-ai/blob/main/src/screens/home_screen.py): landing screen · Role selection and entry routing · `src/screens/home_screen.py`
- [Teacher](https://github.com/ashish1896/attendance-ai/blob/main/src/screens/teacher_screen.py): admin portal · Teacher workflows for subjects, enrollment, sessions, and results · `src/screens/teacher_screen.py`
- [Student](https://github.com/ashish1896/attendance-ai/blob/main/src/screens/student_screen.py): student portal · Student enrollment, verification, and attendance status · `src/screens/student_screen.py`
- [Base layout](https://github.com/ashish1896/attendance-ai/blob/main/src/ui/base_layout.py): shared shell · Common page structure and styling wrapper · `src/ui/base_layout.py`
- [Header](https://github.com/ashish1896/attendance-ai/blob/main/src/components/header.py): chrome component · Shared top-level page chrome · `src/components/header.py`
- [Footer](https://github.com/ashish1896/attendance-ai/blob/main/src/components/footer.py): chrome component · Shared bottom-level page chrome · `src/components/footer.py`
- [Subject card](https://github.com/ashish1896/attendance-ai/blob/main/src/components/subject_card.py): reusable card · Summarizes subject or attendance state · `src/components/subject_card.py`
- [Dialogs](https://github.com/ashish1896/attendance-ai/blob/main/src/components/dialog_enroll.py): workflow modals · Enrollment, photo capture, subject creation, attendance results, sharing, and auto-enroll interactions · `src/components/dialog_enroll.py`
- **Assets**: static media · Branding and visual assets used by the UI

### Browser

Embedded client-side QR capture surface

- [QR scanner](https://github.com/ashish1896/attendance-ai/blob/main/src/components/qr_scanner/index.html): browser widget · Browser-side HTML QR capture embedded in the Streamlit flow · `src/components/qr_scanner/index.html`

### Logic

Local verification and attendance workflows

- [Face verify](https://github.com/ashish1896/attendance-ai/blob/main/src/pipelines/face_pipeline.py): vision pipeline · Normalizes images and matches faces for attendance approval · `src/pipelines/face_pipeline.py`
- [QR validate](https://github.com/ashish1896/attendance-ai/blob/main/src/pipelines/qr_pipeline.py): session pipeline · Validates QR/session tokens and anti-reuse checks · `src/pipelines/qr_pipeline.py`

### Data

Database configuration and persistence access

- [DB config](https://github.com/ashish1896/attendance-ai/blob/main/src/database/config.py): supabase setup · Initializes the Supabase client from Streamlit secrets · `src/database/config.py`
- [DB layer](https://github.com/ashish1896/attendance-ai/blob/main/src/database/db.py): persistence api · CRUD and application queries against Supabase/PostgreSQL · `src/database/db.py`

## Connections

- App entry → Home: routes to · Launches the landing screen and entry routing
- App entry → Base layout: uses shell · Wraps the application in the shared layout
- Base layout → Header: includes · Renders shared top chrome
- Base layout → Footer: includes · Renders shared bottom chrome
- Base layout → Assets: uses · Applies static branding and visual assets
- Home → Teacher: enters · Routes teachers into the administrative portal
- Home → Student: enters · Routes students into the verification portal
- Teacher → Dialogs: invokes · Opens modals for subject, enrollment, photo, share, and results tasks
- Teacher → Subject card: shows · Displays subject summaries and related status
- Student → Dialogs: invokes · Opens enrollment, photo, QR scan, and status dialogs
- Student → QR scanner: embeds · Uses the browser QR capture surface inside the student flow
- Teacher → QR validate: issues sessions · Coordinates session token creation and validation
- Student → QR validate: validates token · Checks scanned QR/session data before check-in
- Student → Face verify: verifies identity · Runs facial verification for attendance approval
- Teacher → DB layer: writes records · Stores subjects, enrollments, sessions, and results
- Student → DB layer: reads writes · Loads history and records attendance events
- DB layer → DB config: initializes via · Uses the Supabase client configured from secrets
- DB config → DB layer: connects · Provides the persistence client to the data layer
- QR validate → DB layer: checks state · Consults session metadata and related records
- Face verify → DB layer: persists outcome · Attendance is recorded after successful verification
