How ashish1896/attendance-ai works
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: student_screen.py Student · db.py DB layer · teacher_screen.py Teacher · base_layout.py Base layout
Components 15
Runtime
Streamlit application entry and process boundary
- App entry · Starts the single Streamlit process and routes into the app shell
app.py
UI
Screens, shared layout, and reusable components
- Home · Role selection and entry routing
src/screens/home_screen.py - Teacher · Teacher workflows for subjects, enrollment, sessions, and results
src/screens/teacher_screen.py - Student · Student enrollment, verification, and attendance status
src/screens/student_screen.py - Base layout · Common page structure and styling wrapper
src/ui/base_layout.py - Header · Shared top-level page chrome
src/components/header.py - Footer · Shared bottom-level page chrome
src/components/footer.py - Subject card · Summarizes subject or attendance state
src/components/subject_card.py - Dialogs · Enrollment, photo capture, subject creation, attendance results, sharing, and auto-enroll interactions
src/components/dialog_enroll.py - Assets · Branding and visual assets used by the UI
Browser
Embedded client-side QR capture surface
- QR scanner · Browser-side HTML QR capture embedded in the Streamlit flow
src/components/qr_scanner/index.html
Logic
Local verification and attendance workflows
- Face verify · Normalizes images and matches faces for attendance approval
src/pipelines/face_pipeline.py - QR validate · Validates QR/session tokens and anti-reuse checks
src/pipelines/qr_pipeline.py
Connections 20
- 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