🔮 TrueFace - AI Face Recognition by Javed Hussain

Real-Time AI Face Recognition System developed by Javed (iamjaved026)
Detect • Recognize • Register — all in your browser

Features • Tech Stack • Quick Start • API • Models • Credits

---

✨ Features

🎯 Real-Time Detection Blazing-fast face detection with TinyFaceDetector running at 15-30 FPS directly in your browser via WebAssembly 🧠 AI Recognition State-of-the-art face embeddings via FaceNet (InceptionResnetV1) trained on VGGFace2 dataset 📷 Live Registration Register new people in seconds — capture 3-5 photos, and they're instantly recognizable

📋 Detection Logs Full history of every recognition event with timestamps, confidence scores, and role info 🎨 Premium Dark UI Futuristic glassmorphism design with smooth animations, scanning effects, and ambient lighting ⚡ One-Command Launch Single node server.js starts both frontend and backend — no complex setup needed

🛠️ Tech Stack

Frontend

Technology	Purpose
Next.js 15	React framework with App Router, SSR
Tailwind CSS 4	Utility-first CSS framework
@vladmandic/face-api	Browser-side face detection (TinyFaceDetector)
TypeScript	Type-safe development

Backend

Technology	Purpose
FastAPI	High-performance Python API framework
FaceNet-PyTorch	MTCNN detection + InceptionResnetV1 embeddings
PyTorch	Deep learning runtime
OpenCV	Image processing
SQLite	Lightweight embedded database

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• Node.js 18+ and npm
• C++ Build Tools (Windows only): Install "Desktop development with C++" via Visual Studio Installer (required by some native Python packages)

1️⃣ Clone the Repository

git clone https://github.com/iamjaved026/trueface.git
cd trueface

2️⃣ Setup Backend

cd backend

# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate

# Activate (macOS/Linux)
# source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

📝 Note: On first run, FaceNet-PyTorch will automatically download the pretrained model weights (~100MB). This only happens once.

3️⃣ Setup Frontend

cd frontend

# Install dependencies
npm install

# Build for production
npm run build

4️⃣ Launch TrueFace

From the project root directory:

node server.js

This single command starts both the FastAPI backend and the Next.js frontend!

╔══════════════════════════════════════════════════════════╗
║         TrueFace — Real-Time Face Recognition           ║
║                        v1.0                             ║
╚══════════════════════════════════════════════════════════╝

[BACKEND]  Starting FastAPI server on port 8000...
[FRONTEND] Starting Next.js on port 3000...

[SERVER]   Dashboard:    http://localhost:3000
[SERVER]   API Docs:     http://localhost:8000/docs

5️⃣ Open the App

Navigate to http://localhost:3000 in your browser and allow camera access.

---

📖 Usage Guide

🔍 Real-Time Recognition

1. Allow camera access when prompted
2. Faces are detected in real-time with futuristic bounding boxes
3. Detected faces are sent to the backend for recognition
4. Known persons show Name (Role) Confidence% in green/blue
5. Unknown persons show Unknown in red

➕ Adding a New Person

1. Click "+ Add Person" in the sidebar
2. Enter the person's name and role (Admin/User)
3. Capture 3-5 images using the circular capture button
4. Click "Register Person"
5. The person is instantly recognizable! 🎉

📋 Viewing Detection Logs

1. Click "Logs" in the sidebar
2. A side panel slides in showing detection history
3. Each entry shows name, timestamp, confidence score, and status

---

🔌 API Reference

Once the backend is running, visit http://localhost:8000/docs for the interactive Swagger UI.

Endpoints

Method	Endpoint	Description
POST	/recognize	Recognize a face from a base64 image
POST	/add-person	Register a new person with face images
GET	/persons	List all registered persons
DELETE	/persons/{id}	Delete a registered person
GET	/logs	Get detection history
DELETE	/logs	Clear all logs
GET	/health	System health check

Example: Recognize a Face

curl -X POST http://localhost:8000/recognize \
  -H "Content-Type: application/json" \
  -d '{"image": "data:image/jpeg;base64,/9j/4AAQ..."}'

Response:

{
  "name": "Javed Hussain",
  "role": "Admin",
  "confidence": 0.892,
  "status": "known"
}

---

📁 Project Structure

trueface/
├── server.js                  # 🚀 Unified launcher (node server.js)
├── LICENSE                    # MIT License
├── .gitignore                 # Git ignore rules
│
├── frontend/                  # Next.js 15 App Router
│   ├── public/models/         # face-api.js model weights
│   └── src/app/
│       ├── components/        # React UI components
│       │   ├── WebcamFeed.tsx     # Live camera + bounding boxes
│       │   ├── AddPersonModal.tsx # Person registration modal
│       │   ├── LogsPanel.tsx      # Detection history panel
│       │   ├── Sidebar.tsx        # Navigation sidebar
│       │   └── StatusIndicator.tsx
│       ├── hooks/             # Custom React hooks
│       │   ├── useFaceDetection.ts  # Browser face detection
│       │   └── useRecognition.ts    # Backend API integration
│       ├── lib/               # Shared utilities
│       │   ├── api.ts            # API client
│       │   └── types.ts          # TypeScript definitions
│       ├── globals.css        # Design system + theme
│       ├── layout.tsx         # Root layout
│       └── page.tsx           # Main dashboard page
│
├── backend/                   # Python FastAPI
│   ├── main.py                # App entry point
│   ├── requirements.txt       # Python dependencies
│   ├── routers/               # API endpoint handlers
│   │   ├── recognize.py          # Face recognition endpoint
│   │   ├── persons.py            # Person CRUD endpoints
│   │   └── logs.py               # Detection log endpoints
│   ├── services/              # Core business logic
│   │   ├── face_service.py       # FaceNet model wrapper
│   │   └── matching.py           # Cosine similarity matching
│   └── database/              # Data persistence
│       ├── db.py                 # SQLite operations
│       └── models.py            # Pydantic models
│

---

⚙️ Configuration

Backend

Setting	File	Default	Description
Recognition Threshold	services/matching.py	0.45	Minimum cosine similarity for a match
Detection Size	services/face_service.py	160×160	MTCNN input resolution
CORS Origins	main.py	localhost:3000	Allowed frontend origins

Frontend

Setting	File	Default	Description
Frame Skip Rate	hooks/useFaceDetection.ts	2	Process every Nth frame
API Base URL	lib/api.ts	http://localhost:8000	Backend API URL
Cache TTL	hooks/useRecognition.ts	1500ms	Recognition result cache duration
Smoothing Factor	hooks/useFaceDetection.ts	0.35	Bounding box EMA smoothing (0-1)

---

🧠 Models & Licenses

TrueFace uses the following pre-trained AI models. No training data is included in this repository. Models are downloaded automatically on first run.

Frontend — Browser-Side Detection

Model	Source	Purpose	License
TinyFaceDetector	@vladmandic/face-api	Real-time face detection in browser	MIT
FaceLandmark68Net	@vladmandic/face-api	68-point facial landmark detection	MIT
FaceRecognitionNet	@vladmandic/face-api	Face descriptor extraction	MIT

@vladmandic/face-api is a modern ES6/TypeScript rewrite of face-api.js by Vladimir Mandic, licensed under MIT.

Backend — Server-Side Recognition

Model	Source	Purpose	License
MTCNN	facenet-pytorch	Multi-task face detection + alignment	MIT
InceptionResnetV1	facenet-pytorch	512-dim face embedding extraction	MIT
Pretrained Weights	VGGFace2 dataset	Face recognition accuracy	CC BY-SA 4.0

facenet-pytorch by Tim Esler provides PyTorch implementations of MTCNN and InceptionResnetV1, pretrained on the VGGFace2 dataset. Licensed under MIT.

Additional Dependencies

Package	Purpose	License
PyTorch	Deep learning runtime	BSD-3-Clause
FastAPI	Python web framework	MIT
Next.js	React framework	MIT
OpenCV	Image processing	Apache-2.0
Pillow	Python image library	MIT-CMU

---

🗺️ Roadmap

• Multi-face tracking with individual recognition
• GPU-accelerated detection via WebGL
• Face anti-spoofing (liveness detection)
• Export/import person database
• Docker containerization
• Role-based access control
• Real-time alerts & notifications

---

🤝 Contributing

Contributions are welcome! Please read the Contributing Guidelines before submitting a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

You are free to use, modify, and distribute this software for personal and commercial purposes.

---

💖 Credits

Built with ❤️ by Javed Hussain Full-Stack Developer & AI Enthusiast

Acknowledgments

• 🙏 Vladimir Mandic — for the excellent face-api library
• 🙏 Tim Esler — for facenet-pytorch and pretrained models
• 🙏 VGGFace2 Team — for the training dataset
• 🙏 Vercel — for Next.js and the amazing developer experience
• 🙏 FastAPI Team — for the blazing-fast Python framework

---

⭐ If you found TrueFace useful, please consider giving it a star!

TrueFace v1.0 — Made in India 🇮🇳