Face Recognition Attendance – Detailed Project Report

1. Overview

This project is a full‑stack face‑recognition attendance system inspired by tools like ubiAttendance, but built to be fully self‑hosted and customizable.

The system enables:

• Student & subject management per teacher
• Face registration (embeddings only, no raw images stored in the database)
• Fast attendance capture from a live webcam feed
• Duplicate prevention (one attendance per student per day/session)
• Multi‑tenant isolation so each teacher sees only their own data
• Dashboards, history, and export for attendance analytics

It is composed of a FastAPI backend and a Next.js 14 frontend, communicating via a documented REST API.

---

2. Technology Stack

2.1 Backend

• Language: Python 3.12
• Framework: FastAPI
• Server: Uvicorn (ASGI)
• Database:
  • PostgreSQL in production
  • SQLite (sqlite:///./attendance.db) for local development
• ORM: SQLAlchemy 2.x
• Validation & settings:
  • Pydantic v2 (request/response models)
  • pydantic-settings (environment‑based config)
• Authentication & security:
  • JWT tokens via python-jose
  • Password hashing via bcrypt
  • admin and teacher roles with role‑based access using FastAPI dependencies
• Face recognition:
  • face_recognition (dlib‑based 128‑dimension embeddings)
  • face_recognition_models
  • opencv-python-headless for image decoding
  • numpy for numeric computations
• Other:
  • CORS middleware for frontend↔backend communication
  • Optional seeding script for demo data

2.2 Frontend

• Language: TypeScript
• Framework: Next.js 14 (App Router)
• UI & styling:
  • React + Tailwind CSS
  • Global dark theme tailored to a “smart classroom dashboard” look
  • Lucide icons for consistent iconography
• HTTP client: Axios with centralized interceptors
• State / Storage:
  • LocalStorage for storing access tokens and user info
• Charts & visualization:
  • Recharts for attendance analytics on the dashboard
• Media:
  • Native navigator.mediaDevices.getUserMedia for webcam video
  • A reusable WebcamCapture component for capture flows

---

3. Backend Architecture

Backend root: backend/app

3.1 Core modules

• main.py

  • Creates the FastAPI app instance.
  • Configures CORS using origins from Settings.cors_origins.
  • Includes all routers:
    • auth_router
    • subjects_router
    • students_router
    • face_router
    • attendance_router
    • analytics_router
  • On startup, calls Base.metadata.create_all(bind=engine) to ensure tables exist.
  • Exposes a /health endpoint.

• config.py

  • Uses BaseSettings to load environment variables.
  • Important settings:
    • DATABASE_URL
    • SECRET_KEY
    • ALGORITHM
    • ACCESS_TOKEN_EXPIRE_MINUTES
    • FACE_MATCH_THRESHOLD
    • FACE_EMBEDDING_MODEL
    • CORS_ORIGINS

• database.py

  • Creates the SQLAlchemy engine for the configured DATABASE_URL.
  • Provides SessionLocal and a get_db dependency for per‑request sessions.

• models.py

  • SQLAlchemy ORM models:

    • User

      • Fields: id, email, hashed_password, full_name, role, created_at
      • Enum UserRole with values admin and teacher
      • Relationships: subjects, students

    • Subject

      • Fields: id, name, code, teacher_id, created_at
      • Each subject belongs to exactly one teacher.
      • Relationship: teacher, students

    • Student

      • Fields: id, student_id, full_name, email, created_at
      • teacher_id – the owning teacher
      • subject_id – optional, linking to Subject
      • Uniqueness:
        • (teacher_id, student_id) unique, so different teachers can reuse IDs without conflict.
      • Relationships: teacher, subject, face_embeddings, attendances

    • FaceEmbedding

      • Fields: id, student_id, embedding_data, created_at
      • embedding_data is a comma‑separated list of 128 floats (128‑dim embedding).

    • Attendance

      • Fields: id, student_id, marked_at, attendance_date, session_id, status
      • Unique constraint on (student_id, attendance_date, session_id) to prevent duplicate marks in the same session/day.

• schemas.py

  • Pydantic models for request/response validation:
    • Auth: LoginRequest, RegisterRequest, TokenResponse, UserResponse
    • Subjects: SubjectCreate, SubjectUpdate, SubjectResponse, SubjectListResponse
    • Students: StudentCreate, StudentUpdate, StudentResponse, StudentListResponse
    • Face: RecognizeResponse
    • Attendance:
      • MarkAttendanceRequest
      • MarkAttendanceResponse (includes already_marked: bool)
      • AttendanceRecord, AttendanceHistoryResponse
      • DailyStat, StatsResponse

• auth.py

  • hash_password / verify_password using bcrypt.
  • JWT helpers:
    • create_access_token(data, expires_delta)
    • decode_token(token)
  • Security dependencies:
    • get_current_user – loads the User from the JWT.
    • require_role(*roles) – ensures the current user has one of the allowed roles; used throughout routers.

3.2 Routers and Endpoints

3.2.1 Auth Router (auth_router.py)

• POST /auth/login

  • Accepts email + password.
  • Validates credentials.
  • Returns JWT access token + basic user info.

• POST /auth/register

  • Accepts email, password, full_name, and role.
  • Prevents duplicate emails.
  • Creates a new User with role teacher or admin.

3.2.2 Subjects Router (subjects_router.py)

All endpoints require admin or teacher role; data is scoped to the current teacher.

• GET /subjects

  • Query: skip, limit, search.
  • Returns subjects belonging to the logged‑in teacher.

• POST /subjects

  • Body: SubjectCreate.
  • Creates a subject for the teacher, preventing duplicates by (name, code) per teacher.

• PUT /subjects/{id}

  • Updates name and/or code for a subject owned by the teacher.

• DELETE /subjects/{id}

  • Deletes a subject; linked students simply lose the subject_id.

3.2.3 Students Router (students_router.py)

All endpoints require admin or teacher. Teachers are restricted to their own students.

• GET /students

  • Query: skip, limit, search, subject_id.
  • For teachers:
    • Filters by Student.teacher_id == user.id.
    • Optionally further filters by Student.subject_id == subject_id.
  • Search covers ID, name, and email.

• GET /students/{id}

  • Fetches a single student, scoped to teacher if applicable.

• POST /students

  • Body: StudentCreate with optional subject_id.
  • Ensures:
    • No duplicate student_id for this teacher.
    • If subject_id is provided, that subject belongs to the current teacher.

• PUT /students/{id}

  • Allows updating student_id, full_name, email, and subject_id.
  • Maintains uniqueness of student_id per teacher.

• DELETE /students/{id}

  • Deletes a student and cascades to face embeddings and attendance via relationships.

3.2.4 Face Router (face_router.py)

• POST /face/register-face

  • Multipart form: student_id, image: File.
  • Steps:
    1. Reads image bytes, decodes to RGB.
    2. Extracts a single face embedding (errors on none/multiple/low‑quality).
    3. Looks up the student within the current teacher’s students.
    4. Stores a FaceEmbedding row (embedding only).

• POST /face/recognize-face

  • Multipart form: image: File, optional expected_student_id.
  • Steps:
    1. Extracts probe embedding.
    2. Loads all embeddings for students owned by this teacher.
    3. Finds closest embedding within a configurable threshold.
    4. If expected_student_id is supplied and mismatch occurs → 400 with a clear message.
    5. Resolves the matched student again within teacher scope; returns { student_id, full_name, confidence }.

3.2.5 Attendance Router (attendance_router.py)

• POST /attendance/mark
  • Body: MarkAttendanceRequest { student_id, session_id? }.
  • Validates that the student belongs to the teacher.
  • Uses UTC now to set:
    • marked_at = now
    • attendance_date = now.date()
  • If an existing attendance record exists for (student_id, attendance_date, session_id):
    • Returns it with already_marked = true.
  • Else:
    • Inserts a new record with status "present" and returns already_marked = false.

3.2.6 Analytics Router (analytics_router.py)

All endpoints are scoped: teachers see only their own students’ records; admins see global data.

• GET /attendance/stats

  • Query: from, to.
  • Aggregates daily present counts and returns:
    • daily: [{ date, present, total }]
    • summary with total_present, total_sessions, total_students.

• GET /attendance/history

  • Query: from, to, student_id, skip, limit.
  • Returns paginated AttendanceRecord list with student IDs and names.

• GET /attendance/export

  • Exports attendance data as CSV or Excel (xlsx) for the chosen range.

---

4. Frontend Architecture

Frontend root: frontend/

4.1 Layout and routing

• Uses Next.js App Router structure.
• Public routes:
  • /login – Sign in
  • /register – Create an account
• Protected routes are under the (protected) segment:
  • /dashboard – summary analytics
  • /students – student list & CRUD
  • /students/[id] – per‑student face registration
  • /subjects – subject management
  • /attendance – live webcam attendance capture
  • /history – attendance history and export

(protected)/layout.tsx:

• Checks authentication using isAuthenticated() and redirects to /login if necessary.
• Provides a shared dark gradient + grid background plus the Navbar.

4.2 API client (lib/api.ts)

Centralized Axios client configured with:

• baseURL from NEXT_PUBLIC_API_URL.
• Request interceptor: attaches Authorization: Bearer <token> when present.
• Response interceptor:
  • For non‑auth endpoints:
    • On 401: clears auth and redirects to /login.
  • For /auth/login and /auth/register:
    • Lets the calling pages handle 401 to display inline error messages.

Typed functions map directly to backend endpoints (login, register, subjects, students, face, attendance, analytics).

4.3 Auth store (lib/auth-store.ts)

• setStoredAuth(accessToken, user) – saves token + user to localStorage.
• getStoredUser() – fetches the stored user.
• clearStoredAuth() – removes both.
• isAuthenticated() – simple boolean based on presence of a token.

4.4 Reusable components

• Navbar

  • Shows app name and nav links (Dashboard, Students, Subjects, Capture, History).
  • Indicates active page with primary color and subtle background.
  • Displays logged‑in user’s email and logout button.

• WebcamCapture

  • Props: onCapture, disabled, className, autoStart.
  • Handles:
    • Starting and stopping camera via getUserMedia.
    • Drawing current video frame to a canvas and returning a JPEG Blob to onCapture.
    • Optional autoStart to turn the camera on automatically (used for the Capture page).

---

5. Key User Flows

5.1 Authentication

1. User navigates to /login.
2. Enters email + password.
3. Frontend calls POST /auth/login.
4. On success:
   • Stores token + user and redirects to /dashboard.
5. On 401:
   • Shows “Incorrect email or password.” in the login card.

Registration (/register) follows a similar pattern but first calls POST /auth/register, then logs in.

5.2 Managing subjects

1. Teacher opens /subjects.
2. Creates subjects like “Mathematics” or “Physics” with optional codes.
3. Subjects are only visible to that teacher.

5.3 Managing students

1. Teacher opens /students.
2. Adds a new student:
   • Inputs student_id, full_name, optional email.
   • Optionally assigns a subject from a dropdown (populated from /subjects).
3. Student appears in the table, filtered by search or subject as needed.

5.4 Registering a student’s face

1. On /students, click Register face for a specific student.
2. The dedicated page:
   • Shows which student is being registered.
   • Prompts to start the camera and capture a single face.
3. On capture:
   • Sends the image + student_id to POST /face/register-face.
   • Backend stores the embedding linked strictly to that student and this teacher.

5.5 Taking live attendance

1. Teacher opens /attendance:
   • Either directly (auto‑detect any known student).
   • Or via Take attendance from a specific student (strict match mode).
2. Camera starts automatically (using autoStart).
3. Students come in a line:
   • Each stands in front of camera and clicks Capture.
4. For each capture:
   • Frontend sends the frame to POST /face/recognize-face.
   • If strict mode is active and the face does not match the selected student:
     • UI displays “Face does not match the selected student.”
   • If recognized:
     • Calls POST /attendance/mark.
     • If first mark today:
       • Shows “Attendance marked successfully.”
     • If already marked:
       • Shows “You have already been marked present for today's lecture.”
     • Displays Recognized: and Marked at: .

The camera remains on the whole time; only the Capture button is pressed for each student.

5.6 Viewing history & exporting

1. Teacher opens /history.
2. Selects a date range (from, to).
3. Page lists all attendance records in that range for this teacher.
4. Buttons allow exporting to:
   • CSV
   • Excel (XLSX)

5.7 Monitoring analytics

1. On /dashboard, teacher sees:
   • Total students.
   • Total attendance marks in the last 30 days.
   • Number of days with recorded data.
   • A bar chart of daily attendance counts.

---

6. Error Handling & Edge Cases

• Auth failures

  • 401 from non‑auth endpoints triggers logout + redirect to /login.
  • 401 from /auth/login or /auth/register simply surfaces the message in the UI.

• Face recognition failures

  • No face / multiple faces / low quality result in 400 with clear messages.
  • Frontend shows those messages in the Result panel.

• Attendance duplicates

  • Backend treats duplicate marks as idempotent, returning the original record and already_marked = true.
  • Frontend reflects this with a different message and the original timestamp.

• Cross‑teacher conflicts

  • Every query for students, subjects, embeddings, or attendance is scoped by teacher_id for teachers.
  • Even when student IDs coincide across teachers, recognition and attendance always resolve the student within the owning teacher’s scope.

---

7. Running the Project

See README.md for exact commands, but at a high level:

1. Install system dependencies for Python + dlib.
2. Create Python virtual environment in backend and install requirements.
3. Configure .env for backend and .env.local for frontend.
4. Run:
   • uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   • npm run dev in frontend.
5. Seed demo data with python -m seed (admin + teacher + demo students & subjects).

---

8. Future Enhancements

Some ideas for extension:

• Class timetable integration (scheduled sessions with automatic session_id).
• Additional roles (e.g. principal, operator).
• Push/email notifications for absentees.
• Better embedding management (e.g. multiple embeddings per student with weighting).
• Face anti‑spoofing checks to detect photos/videos.
• PWA or kiosk mode for dedicated attendance stations.

This report is intended as a comprehensive, GitHub‑ready overview of the system’s architecture, technologies, and workflows. It can be linked from the main README.md or kept as a separate REPORT.md in the repository root.