AttendanceFlow AMS
QR-based attendance for schools, with multi-factor anti-fraud scoring and an offline-capable mobile app.
- Role
- Full-stack developer: architecture, backend, UI, and mobile
- Team
- Solo
- Year
- 2026
- Duration
- 9 months, Oct 2025 to Jun 2026
- Status
- Prototype
Overview
AttendanceFlow AMS replaces paper attendance sheets and the manual Excel re-entry that follows them. Teachers project a rotating HMAC-signed QR code; students scan it from their phone and the scan is validated against four independent signals (token signature, GPS geofence, campus Wi-Fi subnet and device fingerprint) before it is written as a present or late record. Around that core sit role-scoped portals for administrators, teachers, and students: dashboards, timetable management with a change-request workflow, digital absence justifications with document upload, notifications, audit logs, and CSV/PDF reporting for at-risk students.
- HMAC-SHA256 signed QR tokens with a 30-second TTL, single-use nonces, and configurable clock-skew tolerance — a screenshotted code is worthless within half a minute.
- Four-signal validation engine (signature, geofence, Wi-Fi subnet, device fingerprint) with tunable weights and thresholds, so each campus can trade strictness against friction without touching code.
- Offline-first mobile scanning: scans captured without connectivity queue on-device and sync in idempotent batches keyed on session, student and nonce, so a flaky network never produces duplicate or lost records.
- Three role-scoped portals behind RBAC — admin, teacher and student — spanning 32 controllers, 106 routes and 59 Blade views.
- Service-layer architecture: eleven single-responsibility services keep business logic out of controllers and unit-testable in isolation.
- Timetable change-request workflow letting teachers propose session moves that administrators approve or reject, with the full history kept in an audit log.
Stack
- Laravel
- PHP
- Tailwind CSS
- Alpine.js
- MySQL
- Vite
- Chart.js
- Preline UI
- Laravel Sanctum
- Spatie Laravel Permission
- NativePHP Mobile
- PHPUnit
My role
Full-stack developer: architecture, backend, UI, and mobile
Links
The problem
Attendance in most training centers is captured on paper, then re-typed by hand into spreadsheets. That human bridge is the bottleneck: it costs administrative staff hours every week, introduces transcription errors, and delays the data by days. By the time anyone notices a student is at risk of exclusion, the damage is done. Students have no visibility into their own record, and submitting a medical certificate means physically walking it to an office.
The approach
A single system that captures attendance at the source and makes it immediately queryable. Teachers open a session and display a QR code that rotates every 30 seconds; students scan it in the mobile app. Because a QR code on a screen can be photographed and forwarded, the scan alone is not trusted. The server scores it against GPS proximity to campus, the client's Wi-Fi subnet and a known device fingerprint, and the weighted total decides whether the record is accepted as present, downgraded to late, or rejected outright. Justifications, timetable changes, and reporting all live in the same data model, so an approved certificate updates the student's rate the moment an admin clicks approve.
What was hard
A QR code displayed on a projector can be photographed and sent to an absent friend, who scans it from home. Signature verification alone cannot detect this — the token is genuine.
Treat presence as a score rather than a boolean. The HMAC signature is a hard gate worth 100 points, but geolocation (40), Wi-Fi subnet (30) and device fingerprint (30) contribute independently; 70 or above marks present, 40 to 69 marks late for manual review, below 40 is rejected. A remote scan passes the signature and fails the other three.
Trade-off›
No single signal is reliable on its own — GPS drifts indoors, campus Wi-Fi is not universally available, and phones get replaced. Weighting rather than requiring all four means a genuinely present student with a weak GPS lock still gets counted, at the cost of a narrow band where a determined cheater on campus Wi-Fi could still succeed. That band is deliberately routed to 'late' for a human to check.
Classrooms have unreliable connectivity, but attendance must not depend on the network being up at 9:00 sharp.
The mobile client queues scans locally and syncs them as a batch when connectivity returns. OfflineQueueService deduplicates on the session, student and nonce triple before writing, making the sync endpoint fully idempotent. A retried batch is a no-op.
Trade-off›
Offline scans cannot be validated against server-side rate limits at capture time, and their timestamps come from the device clock. This is bounded by the token's own 30-second expiry, evaluated server-side at sync — a stale queued token is rejected regardless of when it was captured.
Not every student has a phone with a working camera, and a system that hard-fails for them is worse than paper.
Every generated token also carries a short human-readable text code, uniquely allocated among live tokens. A student can type the six characters instead of scanning, and teachers retain a manual override on the session roster.
Trade-off›
The text code is easier to relay verbally to someone off-campus than a QR image is, so it leans harder on the geolocation and Wi-Fi signals to stay honest. Manual overrides bypass scoring entirely and are recorded in the audit log for that reason.
Absence rates are read constantly — on dashboards, in at-risk reports, per student, per group, per module — and recomputing them from the raw record table on every view does not scale.
Reporting was isolated behind a ReportingService with a dedicated unit test suite, so the aggregation strategy can be swapped (query, cached, or denormalised) without touching a single controller or view.
Trade-off›
The current implementation still computes on read, which is fine at the pilot's data volume but is the first thing that will need caching or a summary table as history accumulates.
More screens
Timetable management — sessions scheduled across groups and rooms.
01 / 06Results
- QR token lifetime
- 30s
QR token lifetime
Rotating HMAC-signed tokens with single-use nonces; a forwarded screenshot expires before it can be used
- Independent validation signals
- 4
Independent validation signals
Signature, GPS geofence, Wi-Fi subnet and device fingerprint, weighted into one accept/late/reject decision
- Automated tests
- 61
Automated tests
PHPUnit feature and unit suites, with every QR and anti-fraud service covered
- Domain services
- 11
Domain services
Single-responsibility services keeping business logic out of the 32 controllers
- Routes shipped
- 106
Routes shipped
72 web routes across three role portals plus 34 Sanctum-secured API routes for the mobile client
- Database migrations
- 26
Database migrations
Academic structure, attendance, QR security, justifications, timetabling and notifications
