Facial Attendance System

Executive summary

The HRIS now includes an administrator-controlled facial-attendance kiosk on the login page. Administrators define the approved privacy policy, enroll employees, authorize a browser for one branch, and may separately enable face-only identification.

Guide contents

Design principles

Detailed engineering reference: docs/FACIAL_ATTENDANCE_IMPLEMENTATION.md

Work completed

Controls added to the admin policy

How the system works

Enrollment

An enrollment belongs to the employee's company, brand, and assigned branch. Re-enrollment revokes the former template and erases its ciphertext.

Face-only attendance

Decision rules

Attendance slot order

Morning inMorning outAfternoon inAfternoon out

The first empty slot is filled. The system then recalculates the existing schedule, rendered time, lateness, undertime, deductions, and credited days.

Privacy and security controls

Credential and template protection

Retention

The daily purge cryptographically erases expired templates, removes challenges expired for more than one day, and deletes verification events according to each brand's configured retention. The non-biometric attendance record follows the organization's separate attendance policy.

Administration guide

A. Install and configure

1. Verify the existing attendance schema.
2. Run the idempotent facial-attendance installer.
3. Create a dedicated encryption secret and place it in the ignored local privacy configuration.
4. Use HTTPS for every production camera page.
5. Schedule the retention command to run daily.

php backend/scripts/check_facial_attendance_prerequisites.php
php backend/scripts/install_facial_attendance.php
php backend/scripts/purge_facial_attendance_data.php

B. Approve and save the policy

1. Select the intended brand.
2. Open Settings → Facial Attendance.
3. Enter the approved notice version/text, lawful-basis and PIA references, DPO contact, fallback, and retention.
4. Set thresholds based on pilot evidence.
5. Enable facial attendance, confirm DPO/legal approval, and save.
6. Enable 1:N separately only if the approved material explicitly covers face-only identification.

C. Enroll employees

1. Select an active employee with an assigned branch.
2. Explain the approved notice and usable fallback.
3. Record acknowledgment and capture a live face under good lighting.
4. Confirm that the admin page shows an active enrollment and expiry date.

D. Authorize a kiosk

1. Use the physical browser that will operate as the kiosk.
2. Enter a clear device name and select its actual branch.
3. Choose an authorization period and activate the browser.
4. Log out to expose the kiosk panel on the login page.

Revoke lost, repurposed, or untrusted browsers immediately from the active-device list.

Employee kiosk guide

Camera positioning

Understanding messages

Technical reference

Frontend modules

Backend modules

Database tables

facial_attendance_settingsfacial_attendance_devicesemployee_face_templatesfacial_attendance_challengesfacial_attendance_eventsfacial_attendance_audit

Important operational limits

• Challenge validity: two minutes.
• Challenge rate: maximum 10 per device per minute.
• 1:N candidate limit: 500 active templates per branch.
• Duplicate accepted punch window: 60 seconds.
• Device authorization: 1–365 days.
• Policy retention range: 1–3650 days.
• Authoritative timezone: Asia/Manila.

Performance and troubleshooting

Why the first scan can be slower

The first authorized kiosk visit loads and initializes approximately 10 MB of local face models. The implementation now begins this work in the background on the login page. Later scans in the same session reuse the initialized engine.

Performance changes made

• Preload engine after active kiosk status is known.
• Use face-only warm-up rather than full-model warm-up.
• Disable the iris model because the face mesh supplies the eye-close gesture.
• Request a 480 x 480 camera stream instead of 720 x 720.
• Use a lightweight face-mesh stage for the eye-close gesture, followed by one full descriptor, liveness, and anti-spoof stage.
• Run the independent full-stage models through the library's supported asynchronous path.
• Do not reuse descriptor or assurance results across employees.
• Allow 45 seconds for capture while returning more specific failure messages.
• Reset failed model initialization so a subsequent scan can retry.
• Display separate local-scan and server-match timings after success.

Testing and acceptance

Verification already performed

• Idempotent migrations executed against local MariaDB.
• Identification columns and nullable no-ID challenges verified.
• PHP syntax checks passed for facial-attendance endpoints.
• Targeted ESLint checks passed for the React modules.
• A complete Vite production build succeeded.
• Employee/template SQL joins were corrected for database collation differences.

Production acceptance checklist

• DPO/legal approval and the PIA are documented.
• The notice accurately describes the selected 1:1 or 1:N behavior.
• A practical non-biometric fallback is available without retaliation or undue delay.
• The dedicated encryption key is securely configured and recoverably managed.
• HTTPS and exact frontend origins are configured.
• Each kiosk is assigned to the correct branch and expires appropriately.
• Only intended employees are enrolled and acknowledgment is recorded.
• False acceptance and rejection are measured with representative participants.
• All four attendance slots and schedule calculations are verified.
• Ambiguous, spoof, duplicate, expired, revoked-device, and revoked-template cases are tested.
• The purge job is scheduled, monitored, and tested.
• Incident, access-review, employee-request, and revocation procedures are exercised.

Known limitations

• Browser liveness and anti-spoof are MVP controls, not certified presentation-attack detection.
• 1:N comparison is synchronous and linear, with a 500-template branch cap.
• First-time performance depends on kiosk hardware and model delivery speed.
• Thresholds require organization-specific validation.
• Hands-free scanning is active only while the visible kiosk window remains open; closing it stops the camera and retries.
• The attendance policy currently fills four daily slots sequentially.

Source guide: docs/FACIAL_ATTENDANCE_IMPLEMENTATION.md
Deployment gate: docs/FACIAL_ATTENDANCE_DEPLOYMENT.md