README.md

---
title: MacHub
emoji: 🏢
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# Machub Face Recognition Attendance Backend

A production-ready, ONNX-only face detection and recognition backend built with FastAPI, designed to be deployed on Hugging Face Spaces (free CPU tier).

---

## Folder Structure

```text
machub-hf-space/
├── app.py                  ← FastAPI main server
├── detector.py             ← YOLOv8 face detection using ONNX Runtime
├── recognizer.py           ← InsightFace ArcFace matching with CLAHE preprocessing
├── firebase_helper.py      ← Firestore read/write operations (IST & retry resilient)
├── keep_alive.py           ← Prevents Hugging Face Space from sleeping
├── requirements.txt        ← ONNX-only python dependencies
├── Dockerfile              ← Docker container configuration for HF Spaces
├── .env.example            ← Environment variables template
├── models/
│   └── README.md           ← Model download links and configuration details
└── README.md               ← Setup, test, and deployment guide (this file)
```

---

## Setup & Deployment Guide

### STEP 1: Create a Hugging Face Space
1. Go to [huggingface.co/new-space](https://huggingface.co/new-space).
2. Choose a name: `machub-attendance`.
3. Select **Docker** as the SDK.
4. Select **Blank** template.
5. Visibility: **Private** (recommended to keep endpoints hidden).
6. License: **MIT** or any.
7. Click **Create Space**.

### STEP 2: Add Secrets in Hugging Face Space Settings
Go to your Space **Settings** page, scroll down to **Variables and Secrets**, and add the following **Secret** keys (not variables):

| Secret Key | Description / Example Value |
|---|---|
| `FIREBASE_PROJECT_ID` | Your Firebase project ID (e.g., `machub-6af39`) |
| `FIREBASE_PRIVATE_KEY_ID` | Your Firebase credentials Private Key ID |
| `FIREBASE_PRIVATE_KEY` | Your Firebase Private Key (include the begin/end block headers and replace literal newlines if needed, e.g. `-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n`) |
| `FIREBASE_CLIENT_EMAIL` | Firebase Client Email (e.g., `firebase-adminsdk-...@...gserviceaccount.com`) |
| `FIREBASE_CLIENT_ID` | Your Firebase Client ID |
| `API_SECRET_KEY` | Generate a random 32-character string. Save it here AND in `machub-admin` `.env` under `VITE_HF_API_KEY`. |
| `SPACE_URL` | Your Space direct URL (e.g., `https://username-machub-attendance.hf.space`) |

*Note: The FastAPI backend automatically initializes using these secrets.*

### STEP 3: Clone and Push Code
1. Clone your Hugging Face Space repository:
   ```bash
   git clone https://huggingface.co/spaces/YOUR_USERNAME/machub-attendance
   ```
2. Copy all files from `C:/Projects/Machub/machub-hf-space/` (except the `models/` ONNX files to comply with Git repository sizes) into the cloned directory.
3. Commit and push:
   ```bash
   git add .
   git commit -m "deploy: initial face recognition FastAPI server"
   git push
   ```
4. Hugging Face will automatically build and run the Docker image (takes 3-5 minutes). On first boot, the space will auto-download the YOLOv8 and ArcFace models from their releases.

### STEP 4: Keep Space Awake 24/7 (UptimeRobot)
1. Go to [uptimerobot.com](https://uptimerobot.com) and create a free account.
2. Click **Add New Monitor**.
3. Monitor Type: **HTTPS**.
4. Friendly Name: `Machub KeepAlive`.
5. URL: `https://YOUR_USERNAME-machub-attendance.hf.space/health`
6. Monitoring Interval: **Every 5 minutes**.
7. Create Monitor. This keeps your Space awake permanently for free!

---

## Local Development & Testing

Before deploying, you can test the backend server locally on your machine.

### Running Locally
1. Navigate to the folder:
   ```bash
   cd C:/Projects/Machub/machub-hf-space
   ```
2. Copy `.env.example` to `.env` and fill in your Firebase project credentials.
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
4. Run the Uvicorn dev server:
   ```powershell
   # If running on Windows, disable the OpenSSL AES-NI acceleration hardware bug:
   $env:OPENSSL_ia32cap="~0x200000200000000"
   python -m uvicorn app:app --reload --port 7860
   ```

---

## API Testing with Curl Commands

Open a separate terminal window and run the following commands to test. Replace `your-random-secret-key-here` with the `API_SECRET_KEY` value configured in your `.env`.

### 1. Health Check (Public)
```bash
curl -X GET http://localhost:7860/health
```
*Expected Response:*
```json
{
  "status": "online",
  "models": {
    "detector": true,
    "recognizer": true
  },
  "firebase": true,
  "version": "1.0.0"
}
```

### 2. Enroll a Student (Authenticated)
Uploads photos of a student to extract and save their face embedding to Firestore.
```bash
curl -X POST http://localhost:7860/enroll \
  -H "X-API-Key: your-random-secret-key-here" \
  -F "roll_no=BCA001" \
  -F "name=Test Student" \
  -F "division=BCA-A" \
  -F "photos=@/path/to/photo1.jpg" \
  -F "photos=@/path/to/photo2.jpg"
```

### 3. Scan a Classroom Frame (Authenticated)
Uploads a classroom frame to match faces and log attendance.
```bash
curl -X POST http://localhost:7860/scan \
  -H "X-API-Key: your-random-secret-key-here" \
  -F "frame=@/path/to/classroom_frame.jpg" \
  -F "period=1" \
  -F "division=BCA-A"
```