Orbit Edu RFID Turnstile Gate Kiosk, Edge Debouncing & Tardiness Escalation Protocol

1. Operational Mission & Edge Access Architecture

Campus perimeter security and student punctuality tracking demand sub-second validation during peak morning entry windows. Between 07:30 AM and 08:15 AM, hundreds of students arrive simultaneously across multiple pedestrian turnstile lanes. Access control hardware must authenticate credentials, trip physical turnstile solenoids, verify attendance, prevent tailgating and double-swiping, and broadcast notifications without causing entry bottlenecks.

Manual pen-and-paper gate logs fail under morning congestion. They leave guardians unaware of when children arrive at school and introduce delays in compiling official morning absentee lists. Furthermore, inconsistent tardiness enforcement allows habitual truancy to evade pastoral intervention.

Orbit Edu deploys dedicated fullscreen gate kiosk terminals connected to optical barcode scanners, 13.56 MHz RFID readers, and optical biometric turnstiles. Every tap is verified, logged, debounced, and matched against morning assembly cutoffs.

The architecture is implemented in apps/edu/src/app/gate/page.tsx (the fullscreen gate terminal view), apps/api/src/modules/edu/services/gate-attendance.service.ts (the high-throughput gate event engine executing processGateEvent), apps/api/src/modules/edu/services/discipline.service.ts (governing automated conduct infractions), and the underlying AttendanceRecord, GateEventRecord, and DisciplineIncidentReport models.

1.1 Operator Authority Matrix

Execution of gate access operations is distributed across four institutional roles:

1. Gate Security Warden (Tier 1 Operator): Stationed at pedestrian turnstile banks. Monitors the live gate kiosk screen, assists students with damaged badges, and supervises manual visitor gate check-ins.
2. Attendance Clerk (Tier 1 Administrative Liaison): Monitors the live entry stream, investigates students marked absent after assembly cutoff, and coordinates guardian inquiries regarding gate notifications.
3. Discipline Master / Dean of Students (Tier 2 Authority): Reviews automated tardiness incident reports, conducts counseling sessions for students accumulating multiple late slips, and administers after-school detention rosters.
4. Hardware Infrastructure Engineer (Tier 3 Specialist): Manages physical turnstile relay controllers, configures USB keyboard-wedge RFID reader parameters, and sets up network fallback routers.

2. Interactive RFID Gate Kiosk Terminal

The gate terminal runs in fullscreen kiosk mode on touchscreen all-in-one PCs mounted beside physical turnstile lanes:

3. Edge Debouncing & Punctuality State Engine

Turnstile telemetry processing requires robust duplicate protection to handle anxious students tapping multiple times or cards rubbing against sensors. The engine enforces a 120-second cooldown period while routing valid scans through morning assembly cutoffs.

3.1 Edge Debouncing Logic & Volatile Cache Specification

As programmed in gate-attendance.service.ts:

// In-memory debounce map to prevent double-swipes within 120 seconds
// Key: `${tenantId}:${studentId}:${direction}` -> Epoch timestamp
private readonly debounceMap = new Map<string, number>();

const direction = input.direction || 'IN';
const debounceKey = `${activeTenantId}:${student.id}:${direction}`;
const nowEpoch = input.timestamp ? new Date(input.timestamp).getTime() : Date.now();
const lastTapEpoch = this.debounceMap.get(debounceKey) || 0;

if (nowEpoch - lastTapEpoch < 120_000) {
  return {
    success: true,
    debounced: true,
    message: 'Duplicate gate tap ignored (cooldown period active: 120s)',
    studentId: student.id,
    studentName: student.fullName,
    timestamp: new Date().toISOString(),
  };
}
this.debounceMap.set(debounceKey, nowEpoch);

Truthful Architectural Disclosure on In-Memory State

The debounce map operates as a high-speed volatile cache to ensure sub-millisecond evaluation without database locking overhead during peak ingress spikes. Consequently, if the application server or backend worker restarts, the in-memory debounce cache resets. The persistent attendance records written to the relational persistence kernel remain durable, but students scanning within 120 seconds of a server reboot may register an auxiliary scan.

3.2 Tardiness Evaluation & 3-Strike Pastoral Escalation

When an inbound scan occurs after the lateCutoff (08:15 AM), the system tracks late arrivals using rolling monthly accumulators (studentLateCounts):

LateCount = PreviousLateCount + 1

When LateCount >= 3, the system immediately escalates the incident to pastoral discipline:

if (currentLateCount >= 3 && this.disciplineService) {
  await this.disciplineService.fileIncidentReport({
    studentId: student.id,
    studentName: student.fullName,
    admissionNumber: student.admissionNumber,
    className,
    sectionName,
    reporterName: 'Biometric Turnstile Controller',
    reporterRole: 'Turnstile Controller',
    incidentDate: dateStr,
    category: 'TARDINESS_TRUANCY',
    severity: currentLateCount >= 5 ? 'MEDIUM' : 'LOW',
    location: `Gate (${input.deviceId})`,
    description: `Automated tardiness escalation: Student arrived after 08:15 AM assembly cutoff ${currentLateCount} times in ${ym}.`,
    actionRecommended: currentLateCount >= 5 ? 'RED_CONDUCT_SLIP' : 'YELLOW_WARNING_SLIP',
    pointsDelta: -10,
  });
}

4. Operational Runbook: Gate Ingress & Solenoid Triggering

The operational gate routine is organized into three continuous phases: Kiosk Initialization, Morning Peak Processing, and Afternoon Egress Logging.

Phase 1: Terminal Power-On & Kiosk Setup

1. Station Power-Up:

   • Turn on the gate kiosk PC at T-00:45 before morning arrival (07:15 AM).
   • Launch the gate application view at apps/edu/src/app/gate.
   • Press F11 to engage fullscreen kiosk mode.
   • Confirm the USB RFID reader is plugged in and recognized as an active input device.

2. Hardware Relay Diagnostic Test:

   • Tap Test Solenoid Pulse on the administrative panel.
   • The relay controller fires a 200 ms 12V DC pulse to the turnstile solenoid, releasing the locking arm.
   • Confirm the turnstile rotates smoothly through one quadrant and re-locks automatically.

Phase 2: Morning Ingress (07:30 AM – 08:45 AM)

1. Card Presentation & Identification:

   • The student approaches the turnstile lane and taps their physical RFID card against the proximity target.
   • The reader transmits the credential string followed by carriage return.
   • The system queries studentsRepository.findByAdmissionNumber() or matches cardUid.

2. Debounce Validation:

   • Evaluates whether the card was scanned within the previous 120 seconds.
   • If debounced, the screen flashes an amber informational notice (Cooldown Active) without tripping the solenoid or duplicating attendance.

3. Punctuality Evaluation & Relay Pulse:

   • If the current time is on or before 08:15 AM:
     • The terminal sounds a positive chime and flashes green: On-Time — Welcome.
     • Solenoid relay releases; student passes through.
     • Attendance record is upserted with status present.
     • Guardian SMS queue dispatches an on-time arrival confirmation.
   • If the current time is after 08:15 AM:
     • The terminal sounds an alert chime and flashes amber: Late Arrival (08:19 AM).
     • Solenoid relay releases; student passes through.
     • Attendance record is upserted with status late.
     • Guardian SMS queue dispatches a tardiness alert.
     • If late count reaches 3, automated disciplinary escalation files a conduct incident.

Phase 3: Afternoon Egress (01:30 PM – 03:30 PM)

1. Lane Direction Toggle:
   • The security warden toggles the lane direction switch to OUT (Exit Mode).
   • Students tap cards upon leaving campus.
   • The system records egress timestamps, marking attendance status as exited and notifying parents of safe campus departure.

5. Architectural Verification & Throughput Telemetry

The turnstile subsystem is benchmarked under high-density student arrival stress tests:

6. Failure Modes & Recovery SOP

The following operational contingency protocols resolve edge-case exceptions during gate kiosk operations:

7. Cross-Vertical Internal Linkages

The RFID Turnstile Gate Kiosk functions as the perimeter attendance engine, coordinating directly with other modules in the academic network:

• Registrar 360 Student Dossier & Clearance Gates — Binds physical proximity cards to student identity and tracks cumulative attendance rates.
• Pastoral Conduct Scoring & Detention Proctoring — Ingests automated 3rd-strike tardiness incident reports into student conduct scoring dossiers.
• Campus Supervision Duty Rosters & Invigilation Neutrality — Assigns faculty gate supervision duties during morning arrival and afternoon dismissal periods.
• Guardian Self-Service Portal & Turnstile Stream — Streams live gate entry and exit event notifications to parent mobile applications.
• EAN-13 Scale Barcodes & Scanner Wedge Processing — Shares core keyboard-wedge peripheral processing and serial buffer parsing architectures.