SmartFace Attendance

A face-recognition attendance app: React frontend + FastAPI/SQLite backend.

Architecture

Browser (face-api.js runs face detection/recognition
         against the visitor's own webcam)
              │  sends only descriptor arrays + student ids
              ▼
      api/main.py (FastAPI)
              │
              ▼
      SQLite (api/attendance.db)

Face recognition happens client-side, in the visitor's browser. Only the API persists data. This split is deliberate: it's what makes the app deployable as a public link (a cloud server has no webcam of its own), while still giving the project a real backend, database, and tested API.

backend/main.py is a separate, documented experiment with server-side recognition (face_recognition/dlib + OpenCV, live video streaming). It's not used by the deployed app - see the note at the top of that file for why - but it's kept as a record of an architecture decision.

Features

• Register students with name + group using upload or Capture 8 Photos
• Live scanner with face boxes and labels
• Group photo processing for attendance
• Today's attendance table with group filter
• Group-wise attendance matrix (Present / Absent) by date
• Excel export per group, generated on demand from the database
• Full JSON dataset export (backup)

Tech Stack

• React 19 + Vite 8, face-api.js loaded from CDN at runtime
• FastAPI + SQLAlchemy + SQLite (api/)
• pytest (8 passing tests on the API - registration, duplicate rejection, attendance marking, matrix generation, Excel export)

Running locally

Backend (start this first):

cd api
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

Interactive API docs: http://127.0.0.1:8000/docs

Backend tests:

cd api
pytest -v

Frontend:

npm install
npm run dev

Build (Production)

npm run build

Note: the built frontend still needs the API running somewhere it can reach (API_BASE in src/api.js) - it's not a fully static deploy anymore now that attendance is backed by a real database.

Notes

• AI model loading depends on internet access to public CDNs.
• Students and attendance are stored in api/attendance.db (SQLite) - delete that file to reset all data.