--- 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) ```bash # Clone the repository git clone 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 ```bash # 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: ```text 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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 ```bash 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: ```json { "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 ```bash 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 ```bash 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. ```json { "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 ```bash 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 ```bash 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 ```python # 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`): ```bash # 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) ```bash docker-compose up -d ``` ### Docker Production ```bash 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 ```bash # Run tests pytest tests/ -v # Run with coverage pytest tests/ --cov=app ``` ## πŸ“ Database Migrations ```bash # 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 - Documentation: `/docs` (interactive API docs) - Issues: GitHub Issues - Email: support@fmproject.com ## πŸ—ΊοΈ 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 2. Upload files to the space: - `Dockerfile` - `requirements.txt` - `app.py` - `README.md` (this file) 3. 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: ```json { "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: ```json { "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: ```json { "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)