# aditya24rathore/smart-attendance architecture

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

- Interactive diagram: https://gitdiagram.com/aditya24rathore/smart-attendance
- Repository: https://github.com/aditya24rathore/smart-attendance

## Overview

1. This repository is a two-tier attendance system: a React single-page app in `frontend/` talks to a Node.js/Express API in `backend/`, and the backend persists state in MongoDB through Mongoose.

2. The frontend is organized by user role rather than by technical feature. `App.js` and React Router route users into `LoginPage`, `RegisterPage`, `StudentDashboard`, `TeacherDashboard`, and `AdminDashboard`, while reusable UI sits in `components/` such as the navigation bar, student QR display, and teacher QR scanner.

3. The frontend’s only direct backend dependency is the Axios wrapper in `src/services/api.js`. That service layer is the boundary where tokens, base API URL, and request formatting are centralized before requests hit the server.

4. The backend follows a standard route/service/model layering. `routes/` defines API surfaces for `auth`, `student`, `teacher`, and `admin`; `services/` holds business logic for OTP, QR handling, email delivery, and admin bootstrap; `models/` contains the MongoDB document schemas; `middleware/auth.js` enforces authentication and role-based access.

5. Authentication is split across role-specific flows. Students and teachers use OTP-based login/register endpoints under `/api/auth`, while admins have credential login. The backend issues JWTs, and protected routes rely on middleware to validate the token and user role before allowing access.

6. The core attendance workflow is teacher-driven. A teacher starts a session, then uses the scanning UI to capture a student’s QR code; the backend validates the QR payload, ties it to the active session, and creates an attendance record immediately. There is also a manual attendance endpoint for exceptions.

7. Student data is centered on a persistent personal QR code. The QR generation flow lives in `QRService`, with a `QRCode` model present alongside `Student`. The README indicates the QR is enrollment-based and encrypted, so the architecture treats QR creation/verification as a dedicated security-sensitive subsystem, not just a UI feature.

8. Persistence is split by domain: `User` stores shared identity and role information; `Student` and `Teacher` store role-specific profile and academic/organizational fields; `Subject` captures teaching assignments; `Attendance` stores session and scan history; `OTP` stores verification state and expiry metadata. `models/index.js` likely aggregates these schemas for backend use.

9. OTP handling is its own lifecycle. `OTPService` manages generation, verification, attempts, expiry, and reuse prevention, while `clearExpiredOTPs.js` is a maintenance job for cleaning stale records. `EmailService` suggests delivery is abstracted so OTP transport can be email-based or otherwise integrated.

10. Admin capabilities are read/write operations over the same backend data. The admin routes expose system statistics, lists of students and teachers, teacher verification, attendance reports, and bulk attendance updates. `AdminBootstrapService` and `seedAdmin.js` exist to ensure an initial privileged account can be created during setup.

11. The backend entrypoint is `server.js`, which wires together config, database connection from `db.js`, middleware, route registration, and server startup. `config.js` centralizes runtime settings such as port, CORS origin, JWT secret, and database URI.

12. Deployment is environment-driven. The project is configured for Render via `render.yaml`, with the frontend deployed as a static site and the backend as a web service. MongoDB is the primary database; the README explicitly notes that Supabase is not a drop-in fit without migrating the Mongoose layer to PostgreSQL.

13. The main architectural boundary to capture in a diagram is: browser UI → Axios API calls → Express routes → auth/service logic → Mongoose models → MongoDB, with OTP/QR/email services acting as specialized subflows behind the API. The system is role-based, session-based for attendance, and security-sensitive around login and QR validation.

Main entry points: [`frontend/src/services/api.js`](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/services/api.js) (API client), [`backend/routes/admin.js`](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/admin.js) (Admin routes), [`backend/server.js`](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/server.js) (Server), [`frontend/src/App.js`](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/App.js) (App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App<br/>React router shell<br/>[App.js]"]
  node_frontend_api["API client<br/>Axios service<br/>[api.js]"]
  node_frontend_login["Login<br/>Auth page<br/>[LoginPage.js]"]
  node_frontend_register["Register<br/>Auth page<br/>[RegisterPage.js]"]
  node_frontend_student_dash["Student dashboard<br/>Role page"]
  node_frontend_teacher_dash["Teacher dashboard<br/>Role page"]
  node_frontend_admin_dash["Admin dashboard<br/>Role page<br/>[AdminDashboard.js]"]
  node_frontend_nav["Navbar<br/>UI component<br/>[Navbar.js]"]
  node_frontend_qr_display["QR display<br/>UI component"]
  node_frontend_qr_scan["QR scanner<br/>UI component"]
end

subgraph group_backend["Backend"]
  node_server["Server<br/>Express entrypoint<br/>[server.js]"]
  node_config["Config<br/>runtime settings<br/>[config.js]"]
  node_db[("Database<br/>Mongo connection<br/>[db.js]")]
  node_auth_mw["Auth guard<br/>middleware<br/>[auth.js]"]
  node_route_auth["Auth routes<br/>Express routes<br/>[auth.js]"]
  node_route_student["Student routes<br/>Express routes<br/>[student.js]"]
  node_route_teacher["Teacher routes<br/>Express routes<br/>[teacher.js]"]
  node_route_admin["Admin routes<br/>Express routes<br/>[admin.js]"]
  node_otp_service["OTP service<br/>verification logic<br/>[OTPService.js]"]
  node_qr_service["QR service<br/>security logic<br/>[QRService.js]"]
  node_email_service["Email service<br/>delivery adapter<br/>[EmailService.js]"]
  node_admin_bootstrap["Admin bootstrap<br/>setup logic"]
end

subgraph group_data["Data"]
  node_model_index["Models index<br/>schema registry<br/>[index.js]"]
  node_model_user[("User<br/>identity schema<br/>[User.js]")]
  node_model_student[("Student<br/>profile schema<br/>[Student.js]")]
  node_model_teacher[("Teacher<br/>profile schema<br/>[Teacher.js]")]
  node_model_subject[("Subject<br/>assignment schema<br/>[Subject.js]")]
  node_model_attendance[("Attendance<br/>session schema<br/>[Attendance.js]")]
  node_model_otp[("OTP<br/>verification schema<br/>[OTP.js]")]
  node_model_qrcode[("QRCode<br/>credential schema<br/>[QRCode.js]")]
end

subgraph group_ops["Deployment"]
  node_render["Render deploy<br/>deployment config<br/>[render.yaml]"]
end

node_frontend_app -->|"routes to"| node_frontend_login
node_frontend_app -->|"routes to"| node_frontend_register
node_frontend_app -->|"routes to"| node_frontend_student_dash
node_frontend_app -->|"routes to"| node_frontend_teacher_dash
node_frontend_app -->|"routes to"| node_frontend_admin_dash
node_frontend_app -->|"uses"| node_frontend_nav
node_frontend_student_dash -->|"uses"| node_frontend_qr_display
node_frontend_teacher_dash -->|"uses"| node_frontend_qr_scan
node_frontend_login -->|"calls"| node_frontend_api
node_frontend_register -->|"calls"| node_frontend_api
node_frontend_student_dash -->|"calls"| node_frontend_api
node_frontend_teacher_dash -->|"calls"| node_frontend_api
node_frontend_admin_dash -->|"calls"| node_frontend_api
node_frontend_api -->|"hits"| node_route_auth
node_frontend_api -->|"hits"| node_route_student
node_frontend_api -->|"hits"| node_route_teacher
node_frontend_api -->|"hits"| node_route_admin
node_server -->|"loads"| node_config
node_server -->|"connects"| node_db
node_server -->|"registers"| node_auth_mw
node_server -->|"mounts"| node_route_auth
node_server -->|"mounts"| node_route_student
node_server -->|"mounts"| node_route_teacher
node_server -->|"mounts"| node_route_admin
node_route_auth -->|"uses"| node_otp_service
node_route_auth -->|"uses"| node_email_service
node_route_auth -->|"reads/writes"| node_model_user
node_route_student -->|"guards"| node_auth_mw
node_route_student -->|"reads/writes"| node_model_student
node_route_student -->|"reads"| node_model_attendance
node_route_teacher -->|"guards"| node_auth_mw
node_route_teacher -->|"uses"| node_qr_service
node_route_teacher -->|"reads/writes"| node_model_attendance
node_route_teacher -->|"reads"| node_model_subject
node_route_admin -->|"guards"| node_auth_mw
node_route_admin -->|"uses"| node_admin_bootstrap
node_route_admin -->|"reads/writes"| node_model_user
node_route_admin -->|"reads/writes"| node_model_student
node_route_admin -->|"reads/writes"| node_model_teacher
node_route_admin -->|"reads/writes"| node_model_attendance
node_otp_service -->|"persists"| node_model_otp
node_qr_service -->|"persists"| node_model_qrcode
node_qr_service -->|"uses"| node_model_student
node_admin_bootstrap -->|"uses"| node_model_user
node_model_index -->|"exports"| node_model_user
node_model_index -->|"exports"| node_model_student
node_model_index -->|"exports"| node_model_teacher
node_model_index -->|"exports"| node_model_subject

click node_frontend_app "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/App.js"
click node_frontend_api "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/services/api.js"
click node_frontend_login "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/LoginPage.js"
click node_frontend_register "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/RegisterPage.js"
click node_frontend_student_dash "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/StudentDashboard.js"
click node_frontend_teacher_dash "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/TeacherDashboard.js"
click node_frontend_admin_dash "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/AdminDashboard.js"
click node_frontend_nav "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/components/Navbar.js"
click node_frontend_qr_display "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/components/StudentQRDisplay.js"
click node_frontend_qr_scan "https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/components/StudentQRScanner.js"
click node_server "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/server.js"
click node_config "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/config.js"
click node_db "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/db.js"
click node_auth_mw "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/middleware/auth.js"
click node_route_auth "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/auth.js"
click node_route_student "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/student.js"
click node_route_teacher "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/teacher.js"
click node_route_admin "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/admin.js"
click node_otp_service "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/services/OTPService.js"
click node_qr_service "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/services/QRService.js"
click node_email_service "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/services/EmailService.js"
click node_admin_bootstrap "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/services/AdminBootstrapService.js"
click node_model_index "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/index.js"
click node_model_user "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/User.js"
click node_model_student "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/Student.js"
click node_model_teacher "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/Teacher.js"
click node_model_subject "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/Subject.js"
click node_model_attendance "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/Attendance.js"
click node_model_otp "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/OTP.js"
click node_model_qrcode "https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/QRCode.js"
click node_render "https://github.com/aditya24rathore/smart-attendance/blob/main/render.yaml"

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_frontend_app,node_frontend_api,node_frontend_login,node_frontend_register,node_frontend_student_dash,node_frontend_teacher_dash,node_frontend_admin_dash,node_frontend_nav,node_frontend_qr_display,node_frontend_qr_scan toneBlue
class node_server,node_config,node_db,node_auth_mw,node_route_auth,node_route_student,node_route_teacher,node_route_admin,node_otp_service,node_qr_service,node_email_service,node_admin_bootstrap toneAmber
class node_model_index,node_model_user,node_model_student,node_model_teacher,node_model_subject,node_model_attendance,node_model_otp,node_model_qrcode toneMint
class node_render toneRose
```

## Components

### Frontend

React SPA with role-based pages and reusable UI

- [App](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/App.js): React router shell · Routes users into role-specific pages · `frontend/src/App.js`
- [API client](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/services/api.js): Axios service · Centralized backend request wrapper · `frontend/src/services/api.js`
- [Login](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/LoginPage.js): Auth page · Student, teacher, and admin sign-in · `frontend/src/pages/LoginPage.js`
- [Register](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/RegisterPage.js): Auth page · Role-based enrollment and account creation · `frontend/src/pages/RegisterPage.js`
- [Student dashboard](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/StudentDashboard.js): Role page · Student view for QR and attendance context · `frontend/src/pages/StudentDashboard.js`
- [Teacher dashboard](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/TeacherDashboard.js): Role page · Teacher view for session control and scanning · `frontend/src/pages/TeacherDashboard.js`
- [Admin dashboard](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/pages/AdminDashboard.js): Role page · Admin operations and reporting surface · `frontend/src/pages/AdminDashboard.js`
- [Navbar](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/components/Navbar.js): UI component · Shared navigation and session chrome · `frontend/src/components/Navbar.js`
- [QR display](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/components/StudentQRDisplay.js): UI component · Shows the student personal QR code · `frontend/src/components/StudentQRDisplay.js`
- [QR scanner](https://github.com/aditya24rathore/smart-attendance/blob/main/frontend/src/components/StudentQRScanner.js): UI component · Captures QR codes for attendance marking · `frontend/src/components/StudentQRScanner.js`

### Backend

Express API, auth flows, and attendance services

- [Server](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/server.js): Express entrypoint · Bootstraps config, database, middleware, and routes · `backend/server.js`
- [Config](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/config.js): runtime settings · Port, CORS, JWT, and database configuration · `backend/config.js`
- [Database](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/db.js): Mongo connection · Connects the app to MongoDB · `backend/db.js`
- [Auth guard](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/middleware/auth.js): middleware · Validates JWTs and role-based access · `backend/middleware/auth.js`
- [Auth routes](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/auth.js): Express routes · OTP login, registration, and admin credential auth · `backend/routes/auth.js`
- [Student routes](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/student.js): Express routes · Student profile and attendance-facing API · `backend/routes/student.js`
- [Teacher routes](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/teacher.js): Express routes · Teacher session and scanning API · `backend/routes/teacher.js`
- [Admin routes](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/routes/admin.js): Express routes · System stats, reports, verification, and bulk updates · `backend/routes/admin.js`
- [OTP service](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/services/OTPService.js): verification logic · Generates, validates, expires, and reuses OTP state · `backend/services/OTPService.js`
- [QR service](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/services/QRService.js): security logic · Creates and verifies encrypted enrollment QR payloads · `backend/services/QRService.js`
- [Email service](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/services/EmailService.js): delivery adapter · Abstracts OTP delivery channel · `backend/services/EmailService.js`
- [Admin bootstrap](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/services/AdminBootstrapService.js): setup logic · Ensures an initial privileged account exists · `backend/services/AdminBootstrapService.js`

### Data

MongoDB models and persistence boundaries

- [Models index](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/index.js): schema registry · Aggregates Mongo schemas for backend use · `backend/models/index.js`
- [User](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/User.js): identity schema · Shared account identity and role data · `backend/models/User.js`
- [Student](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/Student.js): profile schema · Student-specific academic and enrollment fields · `backend/models/Student.js`
- [Teacher](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/Teacher.js): profile schema · Teacher-specific organizational fields · `backend/models/Teacher.js`
- [Subject](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/Subject.js): assignment schema · Teaching assignments and subject mapping · `backend/models/Subject.js`
- [Attendance](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/Attendance.js): session schema · Attendance sessions and scan history · `backend/models/Attendance.js`
- [OTP](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/OTP.js): verification schema · Verification state, expiry, and retry metadata · `backend/models/OTP.js`
- [QRCode](https://github.com/aditya24rathore/smart-attendance/blob/main/backend/models/QRCode.js): credential schema · Persistent personal QR credential for enrollment · `backend/models/QRCode.js`

### Deployment

Runtime and deployment wiring

- [Render deploy](https://github.com/aditya24rathore/smart-attendance/blob/main/render.yaml): deployment config · Static frontend and web backend deployment definition · `render.yaml`

## Connections

- App → Login: routes to · Router selects authentication entry points
- App → Register: routes to · Router selects enrollment entry points
- App → Student dashboard: routes to · Router selects student experience
- App → Teacher dashboard: routes to · Router selects teacher experience
- App → Admin dashboard: routes to · Router selects admin experience
- App → Navbar: uses · Shared app chrome
- Student dashboard → QR display: uses · Student dashboard presents QR credential
- Teacher dashboard → QR scanner: uses · Teacher dashboard performs attendance scan
- Login → API client: calls · Auth requests go through the API wrapper
- Register → API client: calls · Registration requests go through the API wrapper
- Student dashboard → API client: calls · Student data and attendance calls
- Teacher dashboard → API client: calls · Session and scan calls
- Admin dashboard → API client: calls · Admin reporting and management calls
- API client → Auth routes: hits · Axios client targets auth endpoints
- API client → Student routes: hits · Axios client targets student endpoints
- API client → Teacher routes: hits · Axios client targets teacher endpoints
- API client → Admin routes: hits · Axios client targets admin endpoints
- Server → Config: loads · Startup reads runtime settings
- Server → Database: connects · Startup opens MongoDB connection
- Server → Auth guard: registers · Middleware applied to protected routes
- Server → Auth routes: mounts · Registers auth API surface
- Server → Student routes: mounts · Registers student API surface
- Server → Teacher routes: mounts · Registers teacher API surface
- Server → Admin routes: mounts · Registers admin API surface
- Auth routes → OTP service: uses · OTP lifecycle during login and register
- Auth routes → Email service: uses · Sends verification codes
- Auth routes → User: reads/writes · Creates and authenticates accounts
- Student routes → Auth guard: guards · Student endpoints require token and role checks
- Student routes → Student: reads/writes · Student profile access
- Student routes → Attendance: reads · Student attendance history
- Teacher routes → Auth guard: guards · Teacher endpoints require token and role checks
- Teacher routes → QR service: uses · Validates QR payloads for attendance
- Teacher routes → Attendance: reads/writes · Creates session and scan records
- Teacher routes → Subject: reads · Uses subject assignment context
- Admin routes → Auth guard: guards · Admin endpoints require privileged access
- Admin routes → Admin bootstrap: uses · Supports privileged account setup
- Admin routes → User: reads/writes · Admin account management
- Admin routes → Student: reads/writes · Student management and verification
- Admin routes → Teacher: reads/writes · Teacher management and verification
- Admin routes → Attendance: reads/writes · Reports and bulk attendance updates
- OTP service → OTP: persists · Stores OTP lifecycle state
- QR service → QRCode: persists · Stores and verifies QR credential data
- QR service → Student: uses · Binds QR credential to enrolled student
- Admin bootstrap → User: uses · Creates initial admin account
- Models index → User: exports · Schema registry exposes user model
- Models index → Student: exports · Schema registry exposes student model
- Models index → Teacher: exports · Schema registry exposes teacher model
- Models index → Subject: exports · Schema registry exposes subject model
