FaceID Vision — Biometric KYC & Real-Time Attendance Access System

Production-ready, enterprise-grade Biometric KYC Verification, ICAO 9303 MRZ Parsing with Intelligent Autofill, and Real-Time 1:N Facial Recognition Access Control.

Live Terminal Demo • KYC Onboarding • API Documentation • SonarQube Report

---

🏛️ System Architecture

graph TB
    subgraph Client["Frontend Layer (Next.js 15 + Framer Motion)"]
        UI_KYC["/kyc - 3-Step KYC Wizard & Dynamic Autofill"]
        UI_TERM["/terminal - Real-Time Kiosk & Auto-Scan"]
        UI_LOGS["/logs - Audit Logs Explorer & CSV Export"]
        UI_ID["/identities - Enrolled Vector Registry"]
        AUDIO["Web Audio API - Spatial Synthesizer"]
    end

    subgraph API["Backend Layer (FastAPI Async)"]
        MRZ["MRZ Engine - ICAO 9303 TD1/TD2/TD3 + Checksum"]
        OCR["EasyOCR Engine - Text & Regional ID Fallback"]
        FACE["InsightFace Engine - buffalo_l (512-d ArcFace)"]
        LIVE["Liveness Engine - 3D Pose, Texture & Chrominance"]
    end

    subgraph Storage["Database Layer (PostgreSQL 16 + pgvector)"]
        PGV["pgvector HNSW Index (users_face_embedding_hnsw_idx)"]
        USERS[("users Table")]
        LOGS[("access_logs Table")]
    end

    UI_KYC -->|POST /api/v1/kyc/parse-document| MRZ
    MRZ -->|Fallback| OCR
    UI_KYC -->|POST /api/v1/kyc/verify-and-register| FACE
    FACE --> LIVE
    LIVE -->|1:1 Cosine Similarity >= 0.65| USERS
    USERS --> PGV

    UI_TERM -->|POST /api/v1/access/verify-entry| FACE
    FACE -->|1:N HNSW Vector Search <=>| PGV
    PGV -->|Access Granted / Denied| LOGS
    LOGS --> UI_TERM

Loading

---

🌟 Key Capabilities & Innovation

1. ICAO 9303 MRZ Engine & Dynamic Form Autofill

• Machine Readable Zone (MRZ) Support:
  • TD3 (Passports): 2 lines × 44 characters (P<...).
  • TD1 (ID Cards): 3 lines × 30 characters (I<... / A<... / C<...).
  • TD2 (Official Cards / Visas): 2 lines × 36 characters.
• Weighted Checksum Validation: $$\text{Checksum} = \left( \sum_{i=0}^{n-1} \text{val}(c_i) \times w_{i \pmod 3} \right) \pmod{10} \quad \text{where } \mathbf{w} = [7, 3, 1]$$
• Dynamic Frontend Autofill: Uploading an ID card or passport immediately parses and auto-populates Full Name, Document ID, Nationality (ISO 3-Letter code), Birth Date (YYYY-MM-DD), Expiry Date, and Gender with real-time user editing support.
• Optical OCR Fallback: If MRZ is absent or degraded, seamlessly routes through EasyOCR with CLAHE contrast normalization.

2. Biometric 1:1 KYC Enrollment Pipeline

• ArcFace Normalized 512-d Vectors: High-precision deep facial representation extracted with InsightFace buffalo_l.
• Multi-Factor Anti-Spoofing & Liveness:
  • 3D Pose Symmetry: Evaluates yaw, roll, and pitch angle ratios between eyes, nose, and mouth keypoints.
  • Laplacian Frequency Variance: Detects high-frequency print artifacts, screen replays, and blur.
  • YCbCr Chrominance Spectrum: Validates natural human skin tone color dispersion.
• 1:1 Cosine Similarity Verification: Computes exact match between document photo and live selfie before enrollment ($\ge 0.65$ threshold).

3. Real-Time 1:N Face ID Access Gate & Terminal Kiosk

• High-Speed Viewfinder & Morphing Reticle: Framer Motion animated SVG target guides transitioning smoothly between idle cyan breathing, verified emerald lock-on, and crimson alert.
• Continuous Autonomous Auto-Scan: Automatic biometric capture without manual clicks with a 3-second radial cooldown progress ring to eliminate spam.
• Direction Toggle: Instant switching between 🟢 ENTRY (IN) and 🔴 EXIT (OUT).
• Sub-Millisecond HNSW Search in SQL: $$\text{Similarity} = 1 - (\text{face_embedding} \Leftrightarrow \text{query_vector})$$

4. Apple/Stripe-Grade Web UI & Spatial Audio

• Next.js 15 App Router & Tailwind CSS: Dark glassmorphic aesthetic (#09090b zinc, electric cyan #06b6d4, emerald #10b981, and crimson #ef4444).
• Web Audio API Harmonic Synthesizer: Zero external audio downloads. Generates harmonic success chimes (C5-E5-G5-C6), radar sweeps, and shutter ticks in-browser.
• Audit Logs & Export: Full text search, direction/status filters, pagination, and one-click CSV download.

---

📊 SonarQube Grade-A Quality Gate

Metric	Result	Target	Status
Quality Gate	🟢 PASSED (OK)	Passed	✅ Approved
Overall Test Coverage	98% (73 tests)	$\ge 80%$	🏆 Industry Standard
Reliability Rating	Grade A (1.0)	Grade A	⚡ Zero Bugs
Security Rating	Grade A (1.0)	Grade A	🛡️ Zero Vulnerabilities
Maintainability Rating	Grade A (1.0)	Grade A	🧼 Zero Code Smells
Duplicated Lines Density	0.0%	$\le 3.0%$	✅ Clean Architecture
Cognitive Complexity	$\le 15$ per method	$\le 15$	✅ Modular Design

---

📐 Vector Mathematics & pgvector Indexing

Biometric face embeddings are 512-dimensional $L_2$-normalized vectors generated by the ArcFace backbone (w600k_r50).

Cosine Distance & Similarity

Given stored vector $\mathbf{u}$ and query vector $\mathbf{v}$: $$\text{Cosine Distance}(\mathbf{u}, \mathbf{v}) = \mathbf{u} \Leftrightarrow \mathbf{v} = 1 - \frac{\mathbf{u} \cdot \mathbf{v}}{|\mathbf{u}|_2 |\mathbf{v}|_2}$$ $$\text{Cosine Similarity}(\mathbf{u}, \mathbf{v}) = 1 - (\mathbf{u} \Leftrightarrow \mathbf{v})$$

PostgreSQL HNSW Index Definition

CREATE EXTENSION IF NOT EXISTS vector;

CREATE INDEX IF NOT EXISTS users_face_embedding_hnsw_idx
ON users USING hnsw (face_embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

---

🚀 Quick Start & Deployment

1. Launch with Docker Compose (Recommended)

# Clone repository
git clone https://github.com/brkNx/face-recognition-system.git
cd face-recognition-system

# Build and start all backend, database, and SonarQube services
docker compose up -d --build

2. Launch Next.js 15 Frontend

# Start frontend via npm workspace from root
npm install
npm run dev

# Open in browser
open http://localhost:3000

3. Service Dashboard Directory

Service	URL	Purpose
🎛️ Terminal Kiosk	http://localhost:3000/terminal	Real-time camera viewfinder & auto-scan
🛡️ KYC Onboarding	http://localhost:3000/kyc	3-step MRZ parsing & face registration
📋 Access Audit Logs	http://localhost:3000/logs	Event logs with filters & CSV export
👥 Enrolled Identities	http://localhost:3000/identities	Vector identity directory & management
⚙️ FastAPI Swagger Docs	http://localhost:8000/docs	Interactive API exploration
📊 SonarQube Dashboard	http://localhost:9000/dashboard?id=brkNx_face-recognition-system	Code quality & security audit

---

📡 REST API Reference

Method	Endpoint	Description
POST	/api/v1/kyc/parse-document	ICAO 9303 MRZ extraction & validation with OCR autofill
POST	/api/v1/kyc/verify-and-register	Full KYC pipeline: 1:1 Cosine match + pgvector enrollment
POST	/api/v1/access/verify-entry	1:N real-time biometric recognition & attendance logging (IN/OUT)
GET	/api/v1/access/logs	Paginated attendance logs with filters & sorting
GET	/api/v1/access/logs/export/csv	Download attendance audit logs in CSV format
GET	/api/v1/users	List enrolled identities with face avatars & KYC status
GET	/api/v1/users/{id}	Retrieve individual user profile
DELETE	/api/v1/users/{id}	Permanently delete identity & biometric vector
GET	/api/v1/stats/dashboard	Real-time KPIs & daily traffic statistics
GET	/health	Service health status

---

🧪 Test Suite & Quality Assurance

Run the comprehensive 73-test suite with coverage reporting:

# Run pytest in Docker container
docker exec -e PYTHONPATH=. face-recognition-system-app-1 pytest --cov=app --cov-report=term-missing tests/

# Execute SonarQube automated scan
./run-sonar-scan.sh

# Run continuous background watcher daemon
./watch-sonar.sh

---

📜 License

This project is open-source and licensed under the MIT License.