| # 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 |
| |
