memory/PRD.md

FaceGuard — Advanced Face Recognition Attendance System

Original Problem Statement

User needs improved face recognition that cannot be bypassed by photos or videos. Wants immigration-style face mesh with colorful lines, liveness challenges (blinking, etc), highly accurate and production-ready. Existing codebase was HuggingFace Space FastAPI face-verify with uniface + MiniFASNetV2 (bypassable, no challenge-response liveness, no attendance features).

Architecture

Backend — /app/backend/server.py (FastAPI on :8001)

• RetinaFace face detector (uniface)
• ArcFace buffalo_l identity embeddings (512-d, cosine sim threshold 0.42)
• MiniFASNetV2 ONNX texture-based anti-spoof (defeats screen replays)
• Server-side challenge tokens (in-memory, 120s TTL, single-use) — cannot bypass by replaying without doing the actions
• MongoDB for employees (with embeddings) + attendance logs

Frontend — /app/frontend (React 18 + Tailwind on :3000)

• MediaPipe Face Mesh (468 pts) live in browser via CDN
• Animated gradient mesh overlay (violet → blue → cyan → green) with laser sweep + corner brackets (airport-kiosk aesthetic)
• Client-side liveness detection using landmark math:
  • Blink → Eye Aspect Ratio (EAR)
  • Turn left / right → Yaw estimation from nose vs cheeks
  • Nod → Pitch estimation from nose vs forehead/chin
  • Smile / mouth open → Mouth Aspect Ratio + width vs cheeks
• Randomized 3-challenge sequences per session (issued by backend)
• Framer Motion transitions, Sonner toasts, dark cyber theme

Three-Layer Anti-Spoof Chain

1. Client challenge-response (MediaPipe) — user must do 3 randomized actions live → defeats static photos
2. Server MiniFASNetV2 texture CNN → defeats printed photos & screen replays
3. Server ArcFace cosine match → identity binding

Pages

• / Landing — bento grid, 3-layer tech pitch, hero with scanner image, metric cards
• /register — 3-step: identity form → capture 3 samples with liveness → success
• /attendance — Kiosk-style check-in/check-out with GPS, live mesh scanner, result screen with match/live scores
• /admin — Stats (total/present/late/absent), attendance log table w/ snapshots + GPS, employee cards, CSV export

API Endpoints

• GET /api/health
• POST /api/attendance/challenge → random 3 actions + token
• POST /api/employees — enroll (multiple images → embeddings)
• GET /api/employees / GET /api/employees/{id} / DELETE /api/employees/{id}
• POST /api/face/verify — verify one frame (challenge_token required to strengthen)
• POST /api/attendance — record check-in/out (challenge_token required, GPS metadata)
• GET /api/attendance?date&employee_id / GET /api/attendance/{id}
• GET /api/attendance/stats/summary?date
• GET /api/attendance/export/csv?date&employee_id

What's Implemented (2026-07-31)

• Full 3-layer face recognition & anti-spoofing pipeline (client + server)
• Employee enrollment with real ArcFace embedding storage
• Attendance record with GPS + face snapshot
• Admin dashboard with stats, filterable log table, employee CRUD, CSV export
• Live gradient MediaPipe face mesh overlay + laser sweep + corner brackets (immigration-style)
• Random liveness challenges: blink, turn left, turn right, nod, smile
• All backend flows tested end-to-end via curl (register → verify → check-in → stats → CSV export → delete)

Prioritized Backlog (P0 → P2)

• P1: Store embeddings via secure hashing / normalize thumbnails
• P1: Configurable working hours & late threshold (currently hardcoded 09:00 UTC)
• P2: WebSocket streaming verification for even faster kiosk UX
• P2: Multi-factor: NIK / QR fallback when face fails
• P2: Facial re-enrollment reminder after N months
• P2: Admin auth (currently open)

Tech Stack

FastAPI · uniface (InsightFace ArcFace) · onnxruntime · MiniFASNetV2 · OpenCV · MongoDB (motor) · React 18 · Tailwind · MediaPipe Face Mesh · Framer Motion · Sonner · Lucide React