fmproService / README.md
Hkoradiya123
chore: Update README metadata section with project details
4dba71d
|
Raw History Blame Contribute Delete
14.6 kB
metadata
title: FMPro Service
emoji: πŸ‘€
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false

Face Inference SaaS Platform

A production-grade multi-tenant face recognition API platform built with FastAPI, InsightFace, and MySQL.

UI Preview

The current frontend runs at http://localhost:3000.

Screens

  • Dashboard: http://localhost:3000/dashboard
  • Billing and payment settings: http://localhost:3000/billing
  • Product docs: http://localhost:3000/docs

Notes

  • The dashboard uses a compact profile menu for docs, billing, API keys, admin access, and logout.
  • Billing is usage-based today: API calls and successful recognitions are metered per tenant and user.
  • The billing page stores payment preferences locally for now and is ready to be connected to a real payment provider later.

🎯 Features

Core Capabilities

  • Multi-tenant Architecture: Complete data isolation between customers
  • Face Registration: Register faces from exactly 3 single-person, different-angle images
  • Face Recognition: Real-time face recognition from single frames or video streams
  • Secure APIs: JWT authentication with role-based access control
  • Scalable: Designed for horizontal scaling with Docker & Kubernetes

Security

  • Multi-tenant data isolation at database level
  • JWT access & refresh tokens
  • Role-based access control (ADMIN/USER)
  • Encrypted embeddings
  • Rate limiting & request validation
  • CORS protection

Advanced Features

  • Face quality validation
  • Duplicate face detection
  • Recognition confidence scores
  • Bounding box detection
  • Analytics & monitoring
  • Admin dashboard capabilities

πŸ—οΈ Architecture

β”œβ”€β”€ app/
β”‚   β”œβ”€β”€ main.py              # FastAPI application entry
β”‚   β”œβ”€β”€ core/                # Core configuration & security
β”‚   β”‚   β”œβ”€β”€ config.py        # Settings & environment
β”‚   β”‚   β”œβ”€β”€ database.py      # SQLAlchemy & session management
β”‚   β”‚   β”œβ”€β”€ security.py      # JWT & authentication utilities
β”‚   β”‚   └── middleware.py    # Multi-tenant middleware
β”‚   β”œβ”€β”€ models/              # SQLAlchemy ORM models
β”‚   β”‚   └── __init__.py      # Tenant, User, FaceEmbedding, etc.
β”‚   β”œβ”€β”€ schemas/             # Pydantic request/response schemas
β”‚   β”œβ”€β”€ services/            # Business logic
β”‚   β”‚   β”œβ”€β”€ auth_service.py
β”‚   β”‚   └── recognition_service.py
β”‚   β”œβ”€β”€ api/                 # API routes
β”‚   β”‚   β”œβ”€β”€ auth_routes.py
β”‚   β”‚   β”œβ”€β”€ face_routes.py
β”‚   β”‚   └── admin_routes.py
β”‚   └── utils/               # Utilities
β”‚       └── common.py        # Image processing, face detection
β”œβ”€β”€ docker-compose.yml       # Local development stack
β”œβ”€β”€ Dockerfile               # Multi-stage production build
β”œβ”€β”€ requirements.txt         # Python dependencies
└── .env.example            # Environment template

πŸš€ Quick Start

Prerequisites

  • Docker & Docker Compose (recommended)
  • Python 3.11+ (for local development)
  • MySQL 8+
  • Redis 7+

Option 1: Docker Compose (Recommended)

# Clone the repository
git clone <repository-url>
cd fmproService

# Copy environment template
cp .env.example .env

# Start all services
docker-compose up -d

# Check service health
curl http://localhost/health

# View API docs
open http://localhost/docs

This starts:

  • MySQL database
  • Redis cache
  • MinIO S3 storage
  • FastAPI backend
  • Nginx reverse proxy

Option 2: Local Development

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your local database URL

# Run migrations
alembic upgrade head

# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# API docs available at: http://localhost:8000/docs

πŸ“‘ API Endpoints

Authentication

  • POST /api/auth/register - Register new user & tenant
  • POST /api/auth/login - Login (JWT)
  • POST /api/auth/refresh - Refresh access token
  • GET /api/auth/me - Get current user

Face Operations

  • POST /api/face/register - Register face from exactly 3 images & generate detailed embedding
  • POST /api/face/recognize - Recognize faces in image
  • GET /api/face/embeddings - List registered embeddings
  • GET /api/face/logs - Get recognition logs
  • DELETE /api/face/embeddings/{embedding_id} - Delete embedding

Admin

  • GET /api/admin/analytics - Platform analytics
  • GET /api/admin/users - List all users
  • DELETE /api/admin/users/{user_id} - Delete user
  • POST /api/admin/api-keys - Create third-party API key

Third-Party API

  • POST /api/v1/faces/register - Register face with X-API-Key
  • POST /api/v1/faces/recognize - Recognize faces with X-API-Key

Billing and Payments

Billing is currently usage-metered and exposed in the admin APIs and the frontend billing page.

  • GET /api/admin/usage?period=YYYY-MM - Get monthly usage for the tenant
  • successful_recognitions - Counted when a recognition matches a known face
  • api_calls - Counted on each face register and recognize request

The frontend billing page is available at:

  • http://localhost:3000/billing

It includes:

  • billing profile fields
  • payment method label
  • invoice address
  • auto-renew toggle
  • monthly usage summary for admins

UI Screenshots

Use these live routes as the source of the current screenshots when capturing the UI for documentation:

http://localhost:3000/dashboard
http://localhost:3000/billing
http://localhost:3000/docs

Recommended capture list:

  • Dashboard header and profile menu
  • Billing settings page
  • Docs page billing section

πŸ” Authentication Flow

  1. Register: Create tenant & user account

    curl -X POST http://localhost:8000/api/auth/register \
      -H "Content-Type: application/json" \
      -d '{
        "email": "user@company.com",
        "password": "SecurePassword123",
        "full_name": "John Doe"
      }'
    
  2. Login: Get access token

    curl -X POST http://localhost:8000/api/auth/login \
      -H "Content-Type: application/json" \
      -d '{
        "email": "user@company.com",
        "password": "SecurePassword123"
      }'
    
  3. Use Token: Access protected endpoints

    curl -X GET http://localhost:8000/api/auth/me \
      -H "Authorization: Bearer {access_token}"
    

πŸ‘€ Face Registration Example

Strict rules:

  • exactly 3 images
  • one person per frame
  • no duplicate images
  • 3 different detected face angles
  • one detailed normalized embedding stored
curl -X POST http://localhost:8000/api/face/register \
  -H "Authorization: Bearer {access_token}" \
  -F "person_id=EMP001" \
  -F "name=John Doe" \
  -F "images=@/path/to/front.jpg" \
  -F "images=@/path/to/left.jpg" \
  -F "images=@/path/to/right.jpg" \
  -F "metadata={\"department\": \"Engineering\"}"

🎯 Face Recognition Example

curl -X POST http://localhost:8000/api/face/recognize \
  -H "Authorization: Bearer {access_token}" \
  -F "image=@/path/to/test_frame.jpg" \
  -F "threshold=0.5" \
  -F "return_bboxes=true"

Response:

{
  "faces_detected": 2,
  "recognized": [
    {
      "person_id": "EMP001",
      "name": "John Doe",
      "confidence": 0.96,
      "bbox": [100, 200, 300, 400],
      "embedding_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "unrecognized_count": 1,
  "processing_time_ms": 145.23
}

Third-Party API Integration

Third-party clients use X-API-Key, not JWT. Create key from admin account first.

1. Login As Admin

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@fmproject.dev",
    "password": "Admin@123456"
  }'

Copy access_token.

2. Create API Key

curl -X POST http://localhost:8000/api/admin/api-keys \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "partner-app"
  }'

Response includes api_key. Save it now. It is returned once.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key_name": "partner-app",
  "is_active": true,
  "created_at": "2026-05-07T10:00:00",
  "last_used_at": null,
  "api_key": "fmp_generated_secret_key"
}

3. Register Face From Third-Party App

curl -X POST http://localhost:8000/api/v1/faces/register \
  -H "X-API-Key: {api_key}" \
  -F "person_id=EMP001" \
  -F "name=John Doe" \
  -F "images=@/path/to/front.jpg" \
  -F "images=@/path/to/left.jpg" \
  -F "images=@/path/to/right.jpg" \
  -F "metadata={\"source\":\"partner-app\"}"

4. Recognize Face From Third-Party App

curl -X POST http://localhost:8000/api/v1/faces/recognize \
  -H "X-API-Key: {api_key}" \
  -F "image=@/path/to/test_frame.jpg" \
  -F "threshold=0.5" \
  -F "return_bboxes=true"

Third-party API uses tenant attached to API key. Recognition logs use source third_party_api.

πŸ›‘οΈ Multi-Tenant Isolation

The system ensures strict data isolation:

  1. JWT Validation: Every request validated with tenant_id
  2. Query Filtering: All database queries filtered by tenant_id
  3. Middleware: Custom middleware enforces tenant context
  4. Database Level: Foreign keys prevent cross-tenant access
# Example: Only tenant's embeddings are loaded
embeddings = db.query(FaceEmbedding).filter(
    FaceEmbedding.tenant_id == current_tenant_id
).all()

πŸ“Š Database Schema

Tables

  • tenants: Customer organizations
  • users: Tenant members (admin, user roles)
  • face_embeddings: Stored face vectors & metadata
  • recognition_logs: Audit trail of recognitions
  • api_keys: For programmatic access

All tables include:

  • tenant_id for multi-tenant isolation
  • Appropriate indexes for performance
  • Timestamps for audit

πŸ”§ Configuration

Environment variables (see .env.example):

# Database
DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/fmproject_db

# JWT
SECRET_KEY=your-secret-key-min-32-chars
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Face Recognition
INSIGHTFACE_MODEL=buffalo_l  # buffalo_l, buffalo_s, etc.
INSIGHTFACE_GPU=False
FACE_RECOGNITION_THRESHOLD=0.5

# S3 Storage
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=face-embeddings

# Security
CORS_ORIGINS=["http://localhost:3000"]
RATE_LIMIT_PER_MINUTE=100

πŸ“¦ Deployment

Docker Compose (Development)

docker-compose up -d

Docker Production

docker build -t fmproject-backend:latest .
docker run -d \
  -e DATABASE_URL=mysql+pymysql://... \
  -e SECRET_KEY=your-key \
  -p 8000:8000 \
  fmproject-backend:latest

Kubernetes

See k8s/ directory for Kubernetes manifests (helm charts, deployments, services).

πŸ“ˆ Performance

  • Recognition Latency: < 500ms per frame
  • Throughput: 100+ concurrent users
  • Embedding Storage: Optimized with binary format
  • Caching: Redis for frequently accessed embeddings

πŸ§ͺ Testing

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=app

πŸ“ Database Migrations

# Create migration
alembic revision --autogenerate -m "Add new table"

# Apply migrations
alembic upgrade head

# Rollback
alembic downgrade -1

🀝 Contributing

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

πŸ“„ License

MIT License - see LICENSE file for details

πŸ†˜ Support

πŸ—ΊοΈ Roadmap

  • WebSocket support for real-time recognition
  • Face clustering & grouping
  • Liveness detection
  • Webhooks for events
  • Advanced analytics dashboard
  • Face search API
  • Batch processing
  • GPU acceleration
  • Multi-modal search

Built with ❀️ using FastAPI, InsightFace, and MySQL

  • Name: face-inference-service
  • Space SDK: Docker
  • License: MIT
  1. Upload files to the space:

    • Dockerfile
    • requirements.txt
    • app.py
    • README.md (this file)
  2. Wait for auto-build (2-5 minutes). Space URL will be something like:

    https://your-username-face-inference-service.hf.space
    

Option 2: Direct Python (if you prefer)

Create a app.py with the FastAPI code and add to a Python space type.

API Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "service": "face-inference"
}

Recognize Faces in Frame

POST /recognize
Content-Type: application/x-www-form-urlencoded

Parameters:
- frame_data: Base64-encoded JPEG image
- known_encodings: JSON string with {"encodings": [...], "metadata": [...]}
- tolerance: float (default 0.85)

Response:

{
  "success": true,
  "recognized": [
    {
      "roll_no": "CS001",
      "name": "John Doe",
      "distance": 0.73
    }
  ],
  "count": 1,
  "faces_detected": 1
}

Get Embedding from Image

POST /get_embedding
Content-Type: application/x-www-form-urlencoded

Parameters:
- image_data: Base64-encoded JPEG image

Response:

{
  "success": true,
  "embedding": [0.1, 0.2, ...],
  "faces_detected": 1
}

Usage in Main App

See ../app/utils/inference_client.py for integration example.

Performance Notes

  • First request will be slow (~30-60s) if Space was idle.
  • Paid HF Spaces tier keeps service always-on.
  • Free tier may spin down after inactivity.

Environment Variables

  • FACE_RECOGNITION_MODEL: Model name (default: "buffalo_l")
  • PORT: Service port (default: 7860)