# 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