🧠 Face Recognition Attendance Backend

A production-ready FastAPI backend for real-time face verification and attendance tracking.

📁 Project Structure

face_recognition_backend/
├── .venv/                  # Virtual environment
├── employees/              # Employee photos (for training)
├── encode_faces.py         # Generates face encodings
├── verify.py              # Verify encodings file
├── main.py                # FastAPI backend
├── encodings.pkl          # Trained face encodings (generated)
├── attendance.csv         # Attendance log (auto-generated)
└── requirements.txt       # Dependencies

✅ Setup Complete

Your local environment is ready to run! Here's what's been set up:

1. ✅ Virtual environment activated
2. ✅ All dependencies installed
3. ✅ Face encodings generated (6 employees)
4. ✅ FastAPI server running

🚀 Quick Start

1. Activate Virtual Environment

source .venv/bin/activate

2. Generate Face Encodings (Already Done!)

python encode_faces.py

3. Start the Server

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Server is now running at: http://localhost:8000

🔌 API Endpoints

1. GET / - Health Check

curl http://localhost:8000

Response:

{ "message": "Face Verification Attendance API is running." }

2. GET /employees - List All Employees

curl http://localhost:8000/employees

Response:

{
    "employees": [
        "albert-dera",
        "aiony-haust",
        "wellington-ferreira",
        "jake-nackos",
        "jurica-koletic",
        "John-smith"
    ]
}

3. POST /verify - Verify Face

curl -X POST http://localhost:8000/verify \
  -F "file=@path/to/image.jpg"

Success Response:

{
    "status": "success",
    "name": "John-smith",
    "message": "Welcome, John-smith!"
}

Error Response:

{
    "status": "error",
    "message": "No face detected."
}

🧪 Test with Postman

1. Open Postman
2. Create a new POST request to http://localhost:8000/verify
3. Go to Body → form-data
4. Add key: file (type: File)
5. Upload one of the employee images
6. Send request

📊 Attendance Tracking

Every successful face verification is logged to attendance.csv:

Name	Time	Action
John-smith	2025-10-31 14:22:15	sign_in
albert-dera	2025-10-31 14:25:30	sign_in

🔧 Adding New Employees

1. Add their photo to employees/ folder (name it: firstname-lastname.jpg)
2. Re-run encoding:

   python encode_faces.py

3. Restart the server (it will auto-reload if using --reload flag)

🌐 API Documentation

FastAPI provides automatic interactive API docs:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🐳 Next Steps

Option 1: Deploy to Cloud

• Deploy on Railway, Render, or Fly.io
• Update CORS origins in main.py to your frontend domain

Option 2: Connect React Frontend

Your React app should:

1. Capture webcam photo or let user upload image
2. Send POST request to /verify endpoint
3. Display success/error message

Example React fetch:

const formData = new FormData();
formData.append("file", imageFile);

const response = await fetch("http://localhost:8000/verify", {
    method: "POST",
    body: formData,
});

const result = await response.json();
console.log(result); // {status: "success", name: "John-smith", ...}

🛠️ Troubleshooting

Server won't start

# Check if port 8000 is in use
lsof -i :8000

# Kill process if needed
kill -9 <PID>

No face detected

• Ensure image has clear, front-facing face
• Check image quality and lighting
• Try adjusting tolerance parameter in main.py (line 78)

Low accuracy

• Reduce tolerance: tolerance=0.4 (stricter)
• Use better quality training images
• Ensure consistent lighting

📝 Environment Variables (Optional)

Create a .env file:

ENCODINGS_FILE=encodings.pkl
ATTENDANCE_FILE=attendance.csv
TOLERANCE=0.5

---

Built with:

• FastAPI
• face_recognition
• OpenCV
• Pandas

Ready for production! 🚀