Face Login & Register

A face recognition authentication system using FaceAPI.js (FaceNet) with a React frontend and Node.js backend.

Features

• Face Registration - Captures 5 photos from different angles, extracts 128D FaceNet descriptors
• Face Login - Real-time face detection and recognition with Euclidean distance matching
• Admin Panel - View, delete, import, and export registered users
• GPU Acceleration - WebGL backend for fast face detection and recognition
• Background Blur - Privacy-focused background blur on captured face images
• File System Storage - User data stored on backend file system (not localStorage)

Quick Start

# Install backend dependencies
cd backend && npm install

# Install frontend dependencies
cd frontend && npm install

# Download face recognition models
cd frontend && npm run download-models

# Start backend (terminal 1)
cd backend && npm start

# Start frontend (terminal 2)
cd frontend && npm run dev

Open http://localhost:5173

Pages

Route	Description
/register	Register a new user with face capture
/login	Login with face recognition
/admin	Manage registered users

Architecture

Frontend (React + Vite)    Backend (Express)
     Port 5173                 Port 3001
         |                        |
    face-api.js              File System
    (FaceNet)                backend/users/
         |                        |
    ───── HTTP ──────────►    REST API

API Endpoints

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/users	Get all registered users
POST	/api/register	Register new user (name, descriptors, images)
DELETE	/api/users/:name	Delete a specific user
DELETE	/api/users	Delete all users
POST	/api/import	Import users from JSON

Technology Stack

• Frontend: React 19, TypeScript, Vite
• Face Recognition: face-api.js (FaceNet, TinyFaceDetector)
• Backend: Node.js, Express
• Storage: File system (backend/users/)

Project Structure

├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   ├── Register.tsx      # Face registration
│   │   │   ├── Login.tsx         # Face login
│   │   │   └── Admin.tsx         # User management
│   │   ├── services/
│   │   │   └── api.ts            # API client
│   │   └── utils/
│   │       ├── gpuConfig.ts      # WebGL/CPU backend config
│   │       └── backgroundBlur.ts # Face background blur
│   ├── public/models/            # FaceAPI.js models
│   └── package.json
├── backend/
│   ├── server.js                 # Express API server
│   └── users/                    # User face data storage
├── README.md
└── start.bat / start.sh         # Startup scripts

How It Works

Registration Flow

1. User enters name
2. Camera captures 5 photos (straight, left, right, up, down)
3. FaceAPI extracts 128D descriptors from each photo
4. Descriptors and images sent to backend via POST /api/register
5. Backend creates backend/users/[name]/ with metadata.json and JPEG files

Login Flow

1. Camera detects user's face in real-time
2. FaceAPI extracts 128D descriptor
3. Frontend fetches all users from GET /api/users
4. Compares descriptors using Euclidean distance
5. If distance < 0.6, user is authenticated

Documentation

• FACE_AUTH_IMPLEMENTATION.md - Implementation summary
• FACE_AUTH_README.md - Detailed face recognition docs
• MULTI_FACE_DETECTION.md - Multi-face login detection
• DUPLICATE_DETECTION.md - Duplicate face prevention
• GUIDED_REGISTRATION.md - Registration flow guide
• GPU_ACCELERATION.md - GPU/CPU processing
• IMPORT_EXPORT_GUIDE.md - User data management
• BACKGROUND_BLUR_FEATURE.md - Background blur feature
• backend/README.md - Backend API documentation