# srikruthikapilla/smartattend-ai architecture

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

- Interactive diagram: https://gitdiagram.com/srikruthikapilla/smartattend-ai
- Repository: https://github.com/srikruthikapilla/smartattend-ai

## Overview

Smart Attend is a role-based academic attendance platform. Faculty create time-limited QR sessions; students check in through the public kiosk, where attendance can be verified using facial recognition and liveness, campus geofencing, and optional passkeys. The backend handles authentication, session and attendance APIs, persistence, and real-time updates; administrators and faculty also manage rosters and review analytics and reports. The README documents capabilities beyond the sampled source, so those are represented at subsystem level without assuming unverified internal wiring.

Main entry points: [`backend/app/main.py`](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/main.py) (FastAPI And Socket.IO), [`backend/app/database.py`](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/database.py) (PostgreSQL), [`frontend/src/pages/PublicCheckin.tsx`](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/pages/PublicCheckin.tsx) (Public Check-In), [`frontend/src/context/AttendanceContext.tsx`](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/context/AttendanceContext.tsx) (Attendance Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web Applications"]
  node_app["Role-Based App<br/>[App.tsx]"]
  node_dashboards["Role Dashboards"]
  node_public_checkin["Public Check-In<br/>[PublicCheckin.tsx]"]
end

subgraph group_attendance["Attendance Workflow"]
  node_attendance_context["Attendance Context"]
  node_session_manager["QR Session Manager"]
  node_qr_generator["QR Generator<br/>[QRGenerator.tsx]"]
  node_qr_engine["QR Payload Logic<br/>[qrEngine.ts]"]
  node_live_roster["Live Attendance<br/>[LiveAttendance.tsx]"]
  node_analytics["Analytics And Reports"]
end

subgraph group_identity["Identity And Verification"]
  node_face_enrollment["Face Enrollment"]
  node_face_tools["Face Recognition<br/>[faceRecognition.ts]"]
  node_geofence["GPS Geofencing<br/>[gps.ts]"]
  node_passkey["Passkey Biometrics"]
end

subgraph group_backend["Backend Services"]
  node_api["FastAPI And Socket.IO<br/>[main.py]"]
  node_auth_routes["Authentication Routes<br/>[auth.py]"]
  node_checkin_routes["Check-In Routes<br/>[checkin.py]"]
  node_attendance_routes["Attendance Routes<br/>[attendance.py]"]
  node_qr_routes["QR Session Routes<br/>[qr_session.py]"]
  node_face_routes["Student Face Routes<br/>[student_face.py]"]
  node_webauthn_routes["WebAuthn Routes<br/>[webauthn.py]"]
  node_face_service["Face Matching Service"]
  node_blink["Blink Liveness<br/>[blink_detection.py]"]
  node_webauthn_service["WebAuthn Service"]
end

subgraph group_state["State And Integrations"]
  node_postgres[("PostgreSQL<br/>[database.py]")]
  node_redis["Redis Queue And Cache<br/>[redis_queue.py]"]
  node_email["Email Delivery<br/>[email_service.py]"]
  node_edge_service["Edge Face Service<br/>[app.py]"]
end

node_faculty(("Faculty"))
node_students(("Students"))
node_admins(("Administrators"))
node_browser(("Student Device"))
node_smtp["Brevo SMTP"]
node_socket_clients(("Dashboard Clients"))

node_faculty -->|"uses"| node_app
node_students -->|"uses"| node_app
node_admins -->|"uses"| node_app
node_app -->|"routes to"| node_dashboards
node_students -->|"checks in"| node_public_checkin
node_faculty -->|"starts sessions"| node_session_manager
node_session_manager -->|"starts or ends"| node_attendance_context
node_session_manager -->|"renders"| node_qr_generator
node_qr_generator -->|"generates payload"| node_qr_engine
node_public_checkin -->|"validates payload"| node_qr_engine
node_public_checkin -->|"submits check-in"| node_attendance_context
node_attendance_context -->|"calls API"| node_api
node_live_roster -->|"reads roster"| node_attendance_context
node_analytics -->|"reads attendance"| node_attendance_context
node_face_enrollment -->|"extracts descriptors"| node_face_tools
node_face_enrollment -->|"enrolls passkey"| node_passkey
node_browser -->|"provides location and camera"| node_public_checkin
node_public_checkin -->|"checks location"| node_geofence
node_api -->|"dispatches"| node_auth_routes
node_api -->|"dispatches"| node_checkin_routes
node_api -->|"dispatches"| node_attendance_routes
node_api -->|"dispatches"| node_qr_routes
node_api -->|"dispatches"| node_face_routes
node_api -->|"dispatches"| node_webauthn_routes
node_checkin_routes -->|"verifies face"| node_face_service
node_checkin_routes -->|"checks liveness"| node_blink
node_webauthn_routes -->|"verifies credentials"| node_webauthn_service
node_auth_routes -->|"sends OTP"| node_email
node_email -->|"delivers mail"| node_smtp
node_api -->|"initializes database"| node_postgres
node_checkin_routes -->|"records attendance"| node_postgres
node_attendance_routes -->|"reads and updates"| node_postgres
node_qr_routes -->|"stores sessions"| node_postgres
node_face_routes -->|"stores enrollment"| node_postgres
node_api -->|"starts worker"| node_redis
node_redis -->|"broadcasts updates"| node_socket_clients
node_edge_service -.->|"syncs embeddings"| node_api
node_edge_service -.->|"uses cached embeddings"| node_postgres

click node_app "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/App.tsx"
click node_dashboards "https://github.com/srikruthikapilla/smartattend-ai/tree/main/frontend/src/pages"
click node_public_checkin "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/pages/PublicCheckin.tsx"
click node_attendance_context "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/context/AttendanceContext.tsx"
click node_session_manager "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/pages/admin/QRSessionManager.tsx"
click node_qr_generator "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/components/qr/QRGenerator.tsx"
click node_qr_engine "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/utils/qrEngine.ts"
click node_live_roster "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/pages/LiveAttendance.tsx"
click node_analytics "https://github.com/srikruthikapilla/smartattend-ai/tree/main/frontend/src/pages"
click node_face_enrollment "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/components/face/FaceEnrollmentModal.tsx"
click node_face_tools "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/utils/faceRecognition.ts"
click node_geofence "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/utils/gps.ts"
click node_passkey "https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/utils/webauthnBiometrics.ts"
click node_api "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/auth.py"
click node_checkin_routes "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/checkin.py"
click node_attendance_routes "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/attendance.py"
click node_qr_routes "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/qr_session.py"
click node_face_routes "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/student_face.py"
click node_webauthn_routes "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/webauthn.py"
click node_face_service "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/services/face_recognition_service.py"
click node_blink "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/utils/blink_detection.py"
click node_webauthn_service "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/services/webauthn_service.py"
click node_postgres "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/database.py"
click node_redis "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/services/redis_queue.py"
click node_email "https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/utils/email_service.py"
click node_edge_service "https://github.com/srikruthikapilla/smartattend-ai/blob/main/edge/app.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,node_dashboards,node_public_checkin,node_socket_clients toneBlue
class node_attendance_context,node_session_manager,node_qr_generator,node_qr_engine,node_live_roster,node_analytics toneAmber
class node_face_enrollment,node_face_tools,node_geofence,node_passkey toneMint
class node_api,node_auth_routes,node_checkin_routes,node_attendance_routes,node_qr_routes,node_face_routes,node_webauthn_routes,node_face_service,node_blink,node_webauthn_service toneRose
class node_postgres,node_redis,node_email,node_edge_service,node_faculty,node_students,node_admins,node_browser,node_smtp toneIndigo
```

## Components

### Web Applications

- [Role-Based App](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Role Dashboards](https://github.com/srikruthikapilla/smartattend-ai/tree/main/frontend/src/pages): `frontend/src/pages`
- [Public Check-In](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/pages/PublicCheckin.tsx): `frontend/src/pages/PublicCheckin.tsx`

### Attendance Workflow

- [Attendance Context](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/context/AttendanceContext.tsx): `frontend/src/context/AttendanceContext.tsx`
- [QR Session Manager](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/pages/admin/QRSessionManager.tsx): `frontend/src/pages/admin/QRSessionManager.tsx`
- [QR Generator](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/components/qr/QRGenerator.tsx): `frontend/src/components/qr/QRGenerator.tsx`
- [QR Payload Logic](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/utils/qrEngine.ts): `frontend/src/utils/qrEngine.ts`
- [Live Attendance](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/pages/LiveAttendance.tsx): `frontend/src/pages/LiveAttendance.tsx`
- [Analytics And Reports](https://github.com/srikruthikapilla/smartattend-ai/tree/main/frontend/src/pages): `frontend/src/pages`

### Identity And Verification

- [Face Enrollment](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/components/face/FaceEnrollmentModal.tsx): `frontend/src/components/face/FaceEnrollmentModal.tsx`
- [Face Recognition](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/utils/faceRecognition.ts): `frontend/src/utils/faceRecognition.ts`
- [GPS Geofencing](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/utils/gps.ts): `frontend/src/utils/gps.ts`
- [Passkey Biometrics](https://github.com/srikruthikapilla/smartattend-ai/blob/main/frontend/src/utils/webauthnBiometrics.ts): `frontend/src/utils/webauthnBiometrics.ts`

### Backend Services

- [FastAPI And Socket.IO](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication Routes](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/auth.py): `backend/app/routes/auth.py`
- [Check-In Routes](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/checkin.py): `backend/app/routes/checkin.py`
- [Attendance Routes](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/attendance.py): `backend/app/routes/attendance.py`
- [QR Session Routes](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/qr_session.py): `backend/app/routes/qr_session.py`
- [Student Face Routes](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/student_face.py): `backend/app/routes/student_face.py`
- [WebAuthn Routes](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/routes/webauthn.py): `backend/app/routes/webauthn.py`
- [Face Matching Service](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/services/face_recognition_service.py): `backend/app/services/face_recognition_service.py`
- [Blink Liveness](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/utils/blink_detection.py): `backend/app/utils/blink_detection.py`
- [WebAuthn Service](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/services/webauthn_service.py): `backend/app/services/webauthn_service.py`

### State And Integrations

- [PostgreSQL](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/database.py): `backend/app/database.py`
- [Redis Queue And Cache](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/services/redis_queue.py): `backend/app/services/redis_queue.py`
- [Email Delivery](https://github.com/srikruthikapilla/smartattend-ai/blob/main/backend/app/utils/email_service.py): `backend/app/utils/email_service.py`
- [Edge Face Service](https://github.com/srikruthikapilla/smartattend-ai/blob/main/edge/app.py): `edge/app.py`

### Other components

- **Faculty**
- **Students**
- **Administrators**
- **Student Device**
- **Brevo SMTP**
- **Dashboard Clients**

## Connections

- Faculty → Role-Based App: uses
- Students → Role-Based App: uses
- Administrators → Role-Based App: uses
- Role-Based App → Role Dashboards: routes to
- Students → Public Check-In: checks in
- Faculty → QR Session Manager: starts sessions
- QR Session Manager → Attendance Context: starts or ends
- QR Session Manager → QR Generator: renders
- QR Generator → QR Payload Logic: generates payload
- Public Check-In → QR Payload Logic: validates payload
- Public Check-In → Attendance Context: submits check-in
- Attendance Context → FastAPI And Socket.IO: calls API
- Live Attendance → Attendance Context: reads roster
- Analytics And Reports → Attendance Context: reads attendance
- Face Enrollment → Face Recognition: extracts descriptors
- Face Enrollment → Passkey Biometrics: enrolls passkey
- Student Device → Public Check-In: provides location and camera
- Public Check-In → GPS Geofencing: checks location
- FastAPI And Socket.IO → Authentication Routes: dispatches
- FastAPI And Socket.IO → Check-In Routes: dispatches
- FastAPI And Socket.IO → Attendance Routes: dispatches
- FastAPI And Socket.IO → QR Session Routes: dispatches
- FastAPI And Socket.IO → Student Face Routes: dispatches
- FastAPI And Socket.IO → WebAuthn Routes: dispatches
- Check-In Routes → Face Matching Service: verifies face
- Check-In Routes → Blink Liveness: checks liveness
- WebAuthn Routes → WebAuthn Service: verifies credentials
- Authentication Routes → Email Delivery: sends OTP
- Email Delivery → Brevo SMTP: delivers mail
- FastAPI And Socket.IO → PostgreSQL: initializes database
- Check-In Routes → PostgreSQL: records attendance
- Attendance Routes → PostgreSQL: reads and updates
- QR Session Routes → PostgreSQL: stores sessions
- Student Face Routes → PostgreSQL: stores enrollment
- FastAPI And Socket.IO → Redis Queue And Cache: starts worker
- Redis Queue And Cache → Dashboard Clients: broadcasts updates
- Edge Face Service → FastAPI And Socket.IO: syncs embeddings
- Edge Face Service → PostgreSQL: uses cached embeddings