Realtime Face-Based Authentication

A full-stack demo that registers users with facial embeddings and performs realtime authentication using webcam input. The backend stores embeddings and exposes REST/Socket.IO endpoints, while the frontend uses face-api.js to capture descriptors from the browser and render face landmarks.

Features

• User registration with face embedding, age, and gender detection.
• Realtime authentication via Socket.IO events.
• Webcam-based face detection with landmark overlays.
• PostgreSQL-backed persistence using Prisma.

Tech Stack

Frontend

• React + TypeScript + Vite
• face-api.js for face detection/recognition
• Socket.IO client and Axios
• Tailwind CSS for styling

Backend

• Node.js + Express
• Prisma ORM (PostgreSQL)
• Socket.IO for realtime authentication

Project Structure

.
├── backend
│   ├── prisma
│   │   └── schema.prisma
│   ├── server.js
│   ├── docker-compose.yaml
│   └── package.json
├── frontend
│   ├── src
│   │   ├── components
│   │   │   ├── Authenticate.tsx
│   │   │   └── Register.tsx
│   │   └── App.tsx
│   └── package.json
└── README.md

Prerequisites

• Node.js 18+ (recommended)
• pnpm (recommended) or npm
• PostgreSQL database
• A webcam device for running the frontend

Environment Variables

Create a .env file in backend/ with the following value:

DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DATABASE

Setup

1) Backend

cd backend
pnpm install

Generate the Prisma client and run migrations (or push the schema) against your database:

pnpm prisma generate
pnpm prisma migrate dev
# or: pnpm prisma db push

Start the backend server:

node server.js

The backend listens on http://localhost:3000.

2) Frontend

cd frontend
pnpm install
pnpm dev

The frontend runs on http://localhost:5173 by default.

Usage

1. Open the frontend in a browser and allow camera access.
2. Register a user by entering a name/email and clicking Register.
3. Switch to authentication and click Authenticate to match against stored embeddings.

Face recognition models are loaded at runtime from a CDN in the frontend components.

API Reference

REST Endpoints

• POST /register

  • Body: { name, email, faceEmbedding, gender, age }
  • Response: created user record or error.

• GET /detail/:name

  • Response: the stored face embeddings for the given name.

Socket.IO Events

• authenticate (client → server)

  • Payload: { faceEmbedding }

• authResult (server → client)

  • Payload: { success: boolean, user?: string }

Notes

• backend/docker-compose.yaml defines a MongoDB service, but the current backend uses PostgreSQL via Prisma. If you want MongoDB support, the backend needs to be updated accordingly.
• The authentication match uses Euclidean distance with a threshold of 0.6.

Troubleshooting

• CORS errors: ensure the backend is running on port 3000 and the frontend is on http://localhost:5173 or http://localhost:3000.
• No face detected: make sure the webcam is active and the lighting is adequate.

License

This project is provided as-is for educational purposes.