How aditya24rathore/smart-attendance works
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: api.js API client · admin.js Admin routes · server.js Server · App.js App
Components 31
Frontend
React SPA with role-based pages and reusable UI
- App · Routes users into role-specific pages
frontend/src/App.js - API client · Centralized backend request wrapper
frontend/src/services/api.js - Login · Student, teacher, and admin sign-in
frontend/src/pages/LoginPage.js - Register · Role-based enrollment and account creation
frontend/src/pages/RegisterPage.js - Student dashboard · Student view for QR and attendance context
frontend/src/pages/StudentDashboard.js - Teacher dashboard · Teacher view for session control and scanning
frontend/src/pages/TeacherDashboard.js - Admin dashboard · Admin operations and reporting surface
frontend/src/pages/AdminDashboard.js - Navbar · Shared navigation and session chrome
frontend/src/components/Navbar.js - QR display · Shows the student personal QR code
frontend/src/components/StudentQRDisplay.js - QR scanner · Captures QR codes for attendance marking
frontend/src/components/StudentQRScanner.js
Backend
Express API, auth flows, and attendance services
- Server · Bootstraps config, database, middleware, and routes
backend/server.js - Config · Port, CORS, JWT, and database configuration
backend/config.js - Database · Connects the app to MongoDB
backend/db.js - Auth guard · Validates JWTs and role-based access
backend/middleware/auth.js - Auth routes · OTP login, registration, and admin credential auth
backend/routes/auth.js - Student routes · Student profile and attendance-facing API
backend/routes/student.js - Teacher routes · Teacher session and scanning API
backend/routes/teacher.js - Admin routes · System stats, reports, verification, and bulk updates
backend/routes/admin.js - OTP service · Generates, validates, expires, and reuses OTP state
backend/services/OTPService.js - QR service · Creates and verifies encrypted enrollment QR payloads
backend/services/QRService.js - Email service · Abstracts OTP delivery channel
backend/services/EmailService.js - Admin bootstrap · Ensures an initial privileged account exists
backend/services/AdminBootstrapService.js
Data
MongoDB models and persistence boundaries
- Models index · Aggregates Mongo schemas for backend use
backend/models/index.js - User · Shared account identity and role data
backend/models/User.js - Student · Student-specific academic and enrollment fields
backend/models/Student.js - Teacher · Teacher-specific organizational fields
backend/models/Teacher.js - Subject · Teaching assignments and subject mapping
backend/models/Subject.js - Attendance · Attendance sessions and scan history
backend/models/Attendance.js - OTP · Verification state, expiry, and retry metadata
backend/models/OTP.js - QRCode · Persistent personal QR credential for enrollment
backend/models/QRCode.js
Deployment
Runtime and deployment wiring
- Render deploy · Static frontend and web backend deployment definition
render.yaml
Connections 48
- 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