Real-Time Attendance Management System.
Real-time face recognition-driven attendance tracking with rule-based logic for 11 attendance scenarios
THE
ARCHITECTURE
The system follows an event-driven architecture where a teammate's face recognition service pushes real-time recognition events to a webhook endpoint on the FastAPI backend. Each event is immediately ingested, validated via Pydantic models, and persisted to MongoDB through Motor — the async MongoDB driver — ensuring no blocking I/O on the main thread.
The backend exposes 45+ async REST API endpoints organized around core domain entities: teachers, students, courses, groups, lecture halls, schedules, attendance, simulation, and reports. All endpoints use async/await, allowing the server to handle concurrent requests without thread contention.
MongoDB stores 12 collections including raw attendance events, calculated attendance records, presence sessions, and simulation logs. Compound indexes on frequently queried fields (student ID, course code, date) were benchmarked before and after, resulting in approximately 50% reduction in query response times.
The Next.js (App Router) frontend communicates with the backend via REST, rendering 10 pages including a real-time attendance dashboard, a simulation module for hardware-free testing, and a comprehensive reports page with PDF/Excel export capabilities.
Motor over PyMongo: Since all FastAPI endpoints are async, using the synchronous PyMongo driver would have blocked the event loop on every database call. Motor provides a native async interface to MongoDB, keeping the entire request pipeline non-blocking.
Rule-based logic engine over ML: Attendance classification (late arrival, early exit, unauthorized access, back-to-back lectures, multiple exits etc.) was implemented as a deterministic rule engine rather than a model. This made behavior predictable, auditable, and easy to adjust thresholds (e.g. grace period, late threshold) via environment config without retraining.
Simulation module as a first-class feature: Rather than mocking data in tests, a dedicated simulation endpoint and frontend page were built to create attendance events without camera hardware. And also used 2 cameras during the POC phase and made stakeholder demonstrations straightforward.
Webhook-based ingestion over polling: The face recognition service pushes events to the backend the moment a face is recognized, rather than the backend polling on an interval. This keeps attendance records up to date in real time and reduces unnecessary load.
Key
Technical Decisions
TECHNICAL
CHALLENGES
01. Handling 11 Attendance Scenarios Without Ambiguity
Attendance is rarely binary. A student might arrive late, leave early, take a break, attend a back-to-back lecture, or enter an unauthorized hall. Each combination needed a distinct classification with clear, non-overlapping rules. The challenge was designing a logic engine where edge cases didn't bleed into each other — solved by processing events in strict chronological order per student per day, applying rule priority, and flagging ambiguous records for manual review.
02. Real-Time Webhook Ingestion Without Performance Degradation
During active lecture periods, multiple cameras could push recognition events simultaneously. Using synchronous database writes would have created a bottleneck. By making every API endpoint async and using Motor for non-blocking MongoDB writes, the backend could process concurrent webhook payloads without queuing delays or dropped events.
IMPACT & METRICS