Hikmah Attendance: A Django-Based Facial Recognition Platform with Microservice Architecture

The Challenge: Replacing Manual Roll-Call with Intelligent Attendance

Islamic institutes like Hikmah run multi-year programs with varying durations, multiple sections per week, and new admission batches each year. Manual roll-call is slow, error-prone, and lacks auditable records. The institute needed a system that could handle hands‑free check‑in via facial recognition at classroom kiosks, while also supporting public sharing, leave management, and comprehensive reporting—all without requiring students to log in.

The Solution: A Two-Service Architecture

I built Hikmah Attendance as a custom platform that splits responsibilities cleanly:

• Django handles all business logic: users, courses, enrollments, attendance validation, reporting, and the admin dashboard.
• A dedicated FastAPI microservice (face_service) handles computer vision: face detection, embedding extraction (InsightFace, 512‑d ArcFace), and vector similarity search (FAISS).

This separation allows the ML pipeline to be deployed independently, versioned, and scaled without affecting the core Django application—a pattern ideal for production environments where inference is resource-intensive.

Key Features & Engineering Highlights

1. Complex Academic Domain Modeling

Attendance rules depend on more than just dates. The system models:

• Courses as templates (e.g., “Quranic Sciences”), each with a fixed duration.
• Admission batches (e.g., “Batch 2026”) that anchor the actual start date.
• Course schedules that map a batch to a specific section, weekday, and time window.
• Enrollments that link a student to a batch and section, automatically deriving program start/end dates.

This ensures attendance is only valid within a student’s active enrollment period and during their scheduled class times—preventing cross‑batch marking and reducing administrative overhead.

2. Face Recognition Pipeline

The facial recognition workflow is fully integrated:

• Students register their face during onboarding; the embedding is stored in the database and upserted into a FAISS index.
• At the kiosk, a camera captures a frame, which is sent to the face_service via an internal API.
• The service detects faces, extracts an embedding, and returns the top‑K matches.
• Django verifies the match, applies business rules, and records attendance with a confidence score and metadata (device, IP, timestamp).

The system also supports a public token‑based URL (/p/<token>/mark/) that allows attendance marking without authentication—ideal for shared tablets at institute entrances.

3. Rich Reporting & Operational Tools

Admins and staff have access to:

• Role‑aware dashboards with dynamic charts (Chart.js).
• A full attendance matrix view with date presets, batch/course/section filters.
• One‑click exports to CSV and PDF.
• Leave management (Present/Late/Absent/Leave/Excused) with a 15‑minute grace period for late arrivals.
• Manual overrides for exceptional cases, fully audited by the marking user.

4. Security & Separation of Concerns

• Inter‑service communication is secured with a service token.
• All public endpoints are gated by a random token and protected against CSRF.
• Biometric data is stored separately from the user model, and the system includes placeholder liveness detection for future anti‑spoofing.

Architecture & Engineering Standards

The project follows Django best practices with a clear separation of concerns: business logic is extracted into dedicated services (attendance_marker.py, manual_attendance.py), views remain relatively thin, and domain rules are encapsulated in the model layer. A test suite covers the most critical attendance timeline logic, ensuring that program dates, batch windows, and duplicate marking are correctly enforced.

Developed iteratively over 14 commits, the system has been refined based on direct institute feedback—adding public portals, matrix reports, and export capabilities in response to real‑world operational needs.

The Result

Hikmah Attendance is now a fully functional, production‑ready attendance platform that:

• Reduces administrative friction with facial recognition at the door.
• Provides a single source of truth for student attendance across multiple programs and sections.
• Offers transparent reporting for students, teachers, and admin staff.
• Is built to evolve—the microservice architecture allows future upgrades to the face model without touching the core business logic.

---

Interested in a custom internal tool for your organization? Check out my other engineering projects or reach out to me to discuss how we can build a tailored solution for your unique operational needs.