What if your school's attendance system roasted late teachers?
We built a real-time PIN-based attendance kiosk for a Nigerian secondary school that does more than track clock-ins — it cracks jokes, blocks early leavers, guards against incomplete diaries, and automatically deducts salaries for habitual latecomers. All running on a single school laptop in the staff room.
The Problem
The school had paper sign-in sheets. Teachers signed whenever they felt like it. Some signed for colleagues. The principal had no real-time visibility into who was actually present. Salary discussions around punctuality turned into arguments with no data.
They wanted something that felt like an ATM — walk up, punch in your PIN, see your status, done. No login screens, no passwords to forget, no desktop app to install.
What We Built
A full-screen kiosk web application running on a dedicated laptop in the staff room. Here's what happens when a teacher walks in:
- Type their 4-digit PIN on an on-screen number pad
- System identifies them in under 200ms
- Clock-in recorded with exact timestamp
- Status determined — on time, late, or early bird
- Funny message displayed based on their arrival time
- Salary deduction triggered automatically if late (with monthly caps)
The PIN Authentication Challenge
The obvious approach — store PINs with BCrypt and iterate through all staff — doesn't scale. With 150+ teachers, BCrypt's intentional slowness means a PIN lookup takes 3-5 seconds. Not acceptable for a kiosk experience.
Our solution: dual-hash architecture.
We store two hashes per PIN:
- BCrypt hash — for security (one-way, salt-based, industry standard)
- SHA256 lookup hash — for O(1) PIN identification with a unique database index
When a teacher enters their PIN, we first hash it with SHA256 and look it up against the indexed column — instant match. Then we verify against the BCrypt hash for security confirmation. The result: sub-200ms identification with no compromise on security.
Brute-force protection: 5 failed attempts locks the PIN for 15 minutes. Rate limiting caps the endpoint at 10 requests per minute. These are tracked per-PIN, not per-IP, so one attacker can't lock everyone out.
The Funny Messages Engine
This is what makes teachers actually enjoy using the kiosk. Based on arrival time relative to the school's configured cutoff, the system randomly selects from categorised message pools:
Early arrivals (before cutoff):
"Early bird! The worm is all yours!"
"You beat the sun today. Impressive."
"The staffroom is still warming up, but you're already here!"
Right on time:
"Perfect timing! Not a second wasted."
"You arrived exactly when you should. Precision!"
Late arrivals:
"Better late than never... but barely!"
"You're fashionably late. Emphasis on late."
"Traffic? Alarm clock? Let's not play this game."
Clock-out messages:
"Drive safe! We need you back tomorrow."
"Another day survived. See you bright and early!"
The school specifically requested: "Don't use pidgin — just funny professional English that will shame them a little." The messages are light enough to get a laugh but pointed enough to discourage lateness.
The Salary Deduction System
This is where it gets serious. Every late clock-in automatically creates a LatenessDeduction record:
- Configurable deduction amount per late arrival
- Monthly cap — deductions stop after a configured maximum per month
- Deduction amount shown at clock-in: "Good morning, Mrs. Bello! (₦500 deducted — 3rd lateness this month)"
- Waive/unwaive capability — HR or principal can waive individual deductions with a reason (audit trail maintained)
- Plea system — teachers can submit a formal plea to HR, which escalates to the principal for approval/rejection
The deductions feed into the payroll system, appearing as line items on salary vouchers with full traceability.
The Clock-Out Gauntlet
Leaving isn't as simple as punching your PIN. The system runs a series of checks:
Check 1: Is it closing time yet?
Teachers cannot clock out before the configured closing time unless granted explicit early departure permission by admin. The permission includes a specific permitted time — you can't leave at 1pm if your permission says 2pm.
Check 2: Did you finish your diary?
If diary completion checking is enabled, the system calls a DailyDiaryCompletionChecker service that verifies the teacher has filled in class diary entries for all their scheduled periods that day. Missing entries trigger a block:
"Clock out denied! Your diary has 3 blank spots crying for attention."
"The exit is that way... after you finish your missing entries."
Admin can exempt individual teachers from this check for the day.
Check 3: Are you blocked?
The principal can manually block a specific teacher's clock-out with a reason. The teacher sees:
"The principal has blocked your clock-out. Reason: Parent meeting at 3pm."
Admin can unblock from the admin panel.
The Kiosk UI
The frontend is a Stimulus controller that creates an ATM-style experience:
- Full-screen dark interface with large number pad buttons
- Live clock showing current time prominently
- PIN entry with dots (like a phone lock screen)
- Loading spinner during PIN verification
- Success/error states with the funny messages
- Auto-reset after 5 seconds ready for the next teacher
- Stats bar showing today's attendance count
No mouse needed — teachers tap the on-screen number pad. The entire interaction takes under 10 seconds.
Technical Architecture
┌──────────────────────────────────┐
│ Staff Room Laptop (Kiosk Mode) │
│ ┌────────────────────────────┐ │
│ │ Stimulus Controller │ │
│ │ (ATM-style number pad) │ │
│ │ │ │
│ │ ┌──┐ ┌──┐ ┌──┐ │ │
│ │ │1 │ │2 │ │3 │ ● ● ● ●│ │
│ │ ├──┤ ├──┤ ├──┤ │ │
│ │ │4 │ │5 │ │6 │ │ │
│ │ ├──┤ ├──┤ ├──┤ │ │
│ │ │7 │ │8 │ │9 │ │ │
│ │ ├──┤ ├──┤ ├──┤ │ │
│ │ │C │ │0 │ │ ✓│ │ │
│ │ └──┘ └──┘ └──┘ │ │
│ └────────────────────────────┘ │
│ │ JSON API │
│ ▼ │
│ ┌────────────────────────────┐ │
│ │ KioskController │ │
│ │ - SHA256 lookup (O(1)) │ │
│ │ - BCrypt verify │ │
│ │ - Lateness detection │ │
│ │ - Diary completion check │ │
│ │ - Early departure check │ │
│ │ - Clock-out block check │ │
│ │ - Deduction creation │ │
│ │ - Funny message selection │ │
│ └────────────────────────────┘ │
└──────────────────────────────────┘
Key Design Decisions
Why a web app, not a native kiosk app?
Updates deploy instantly. No APK installs, no version management on the laptop. Open Chrome in kiosk mode (--kiosk flag) and it behaves like a native app. The school's IT person doesn't need to touch the laptop after initial setup.
Why PINs, not fingerprints or face recognition?
Cost and reliability. Fingerprint scanners break. Face recognition needs cameras and ML infrastructure. A 4-digit PIN is free, works instantly, and teachers already understand the concept from ATMs and phone locks. The dual-hash system makes it secure enough for attendance purposes.
Why funny messages?
Culture. Schools run on social accountability. A teacher who gets "You're fashionably late. Emphasis on late." in front of colleagues waiting to clock in will think twice about their alarm clock tomorrow. The messages create a culture of punctuality through peer pressure and humour — far more effective than stern warnings.
Results
Since deployment:
- Clock-in compliance jumped from ~60% to 95% — teachers actually use it because it's quick and entertaining
- Lateness dropped by 40% in the first month — the salary deduction threat is real
- Diary completion improved — teachers who used to leave entries blank now fill them to avoid the clock-out block
- Principal has real-time visibility — the admin dashboard shows who's in, who's late, and attendance trends
This system is part of a comprehensive school management platform built with Rails 8, Hotwire, and Tailwind CSS. The kiosk handles 150+ daily clock-ins with sub-200ms response times on a standard school laptop.
Interested in building something similar for your organisation? Let's talk.
Leave a comment