𝗛𝗼𝘄 𝗜 𝗕𝘂𝗶𝗹𝘁 𝗮𝗻 𝗔𝗜-𝗣𝗼𝘄𝗲𝗿𝗲𝗱 𝗖𝗮𝗺𝗽𝘂𝘀 𝗠𝗮𝗻𝗮𝗴𝗲𝗺𝗲𝗻𝘁 𝗦𝘆𝘀𝘁𝗲𝗺 𝗳𝗿𝗼𝗺 𝗦𝗰𝗿𝗮𝘁𝗰𝗵

A step-by-step breakdown of building TechPhantom AI Campus — real-time facial attendance, full-stack architecture, and everything in between.

────────────────────────────────────

me

𝗧𝗵𝗲 𝗣𝗿𝗼𝗯𝗹𝗲𝗺 𝗪𝗼𝗿𝘁𝗵 𝗦𝗼𝗹𝘃𝗶𝗻𝗴

Every university I’ve seen handles attendance the same way: a teacher calls names, students raise hands, and someone scribbles on a sheet. In a class of 60 students, this wastes 5–10 minutes every single session. Multiply that across hundreds of courses and an entire semester — you’re looking at thousands of hours lost, unreliable records, and rampant proxy attendance.

I decided to build something that eliminates this entirely. Not just a digital register — a fully AI-powered system where a camera does the job automatically, with zero manual input from the teacher or the student.

This is the story of exactly how I built it.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟭 — 𝗗𝗲𝗳𝗶𝗻𝗲 𝘁𝗵𝗲 𝗦𝘆𝘀𝘁𝗲𝗺 𝗕𝗲𝗳𝗼𝗿𝗲 𝗪𝗿𝗶𝘁𝗶𝗻𝗴 𝗮 𝗦𝗶𝗻𝗴𝗹𝗲 𝗟𝗶𝗻𝗲 𝗼𝗳 𝗖𝗼𝗱𝗲

The most common mistake developers make is jumping straight into code. I spent the first few days just thinking through what the system actually needed to do.

𝗧𝗵𝗿𝗲𝗲 𝘁𝘆𝗽𝗲𝘀 𝗼𝗳 𝘂𝘀𝗲𝗿𝘀: • 𝗔𝗱𝗺𝗶𝗻 — manages students, courses, sessions, monitors attendance • 𝗦𝘁𝘂𝗱𝗲𝗻𝘁 — views their own attendance, enrolls in courses, registers their face • 𝗞𝗶𝗼𝘀𝗸 (𝗟𝗶𝘃𝗲 𝗦𝗰𝗮𝗻𝗻𝗲𝗿) — a camera-based terminal that recognizes faces and marks attendance in real time

𝗖𝗼𝗿𝗲 𝗳𝗹𝗼𝘄𝘀 𝗜 𝗵𝗮𝗱 𝘁𝗼 𝘀𝘂𝗽𝗽𝗼𝗿𝘁:

1. Admin creates a course → enrolls students → starts an attendance session
2. Student registers their face via webcam → system encodes and stores it
3. Live camera feed streams to backend → backend matches faces → records attendance
4. Both admin and student see live updates instantly

𝗧𝗵𝗲 𝗻𝗼𝗻-𝗻𝗲𝗴𝗼𝘁𝗶𝗮𝗯𝗹𝗲𝘀: • Real-time — no polling, must use WebSockets • Privacy-safe — store face encodings, never raw images • Role-based access — admins cannot do student things and vice versa • Must work even if heavy AI libraries aren’t installed (fallback mode)

Only after this clarity did I start setting up the project.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟮 — 𝗣𝗿𝗼𝗷𝗲𝗰𝘁 𝗦𝘁𝗿𝘂𝗰𝘁𝘂𝗿𝗲 & 𝗘𝗻𝘃𝗶𝗿𝗼𝗻𝗺𝗲𝗻𝘁 𝗦𝗲𝘁𝘂𝗽

I chose a clean separation: one 𝗯𝗮𝗰𝗸𝗲𝗻𝗱/ folder for Python/FastAPI, and one 𝗳𝗿𝗼𝗻𝘁𝗲𝗻𝗱/ folder for React/Vite. Keeping them completely independent means either side can be swapped, redeployed, or scaled without touching the other.

The backend used a Python virtual environment to isolate dependencies — 𝗙𝗮𝘀𝘁𝗔𝗣𝗜, 𝗦𝗤𝗟𝗔𝗹𝗰𝗵𝗲𝗺𝘆, 𝗣𝘆𝗱𝗮𝗻𝘁𝗶𝗰, JWT libraries, 𝗢𝗽𝗲𝗻𝗖𝗩, and face_recognition. The frontend used npm with 𝗥𝗲𝗮𝗰𝘁, 𝗔𝘅𝗶𝗼𝘀, Lucide Icons, 𝗥𝗲𝗰𝗵𝗮𝗿𝘁𝘀, and react-webcam.

Having a clear folder structure from day one prevented the chaos of a disorganized codebase as the project grew.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟯 — 𝗗𝗲𝘀𝗶𝗴𝗻 𝘁𝗵𝗲 𝗗𝗮𝘁𝗮𝗯𝗮𝘀𝗲 𝗠𝗼𝗱𝗲𝗹𝘀

Before writing any API, I designed the full database schema. This is the foundation everything else sits on — get it wrong and you’ll be rewriting half the app later.

I needed 5 entities:

𝗨𝘀𝗲𝗿 → Authentication for both admins and students 𝗦𝘁𝘂𝗱𝗲𝗻𝘁 → Extended profile linked to a User 𝗖𝗼𝘂𝗿𝘀𝗲 → A university course with a unique code 𝗔𝘁𝘁𝗲𝗻𝗱𝗮𝗻𝗰𝗲𝗦𝗲𝘀𝘀𝗶𝗼𝗻 → A time-bounded window opened by an admin 𝗔𝘁𝘁𝗲𝗻𝗱𝗮𝗻𝗰𝗲𝗥𝗲𝗰𝗼𝗿𝗱 → One attendance entry per student per session

The trickiest relationship was 𝗦𝘁𝘂𝗱𝗲𝗻𝘁 ↔ 𝗖𝗼𝘂𝗿𝘀𝗲 — a student can be in many courses, and a course has many students. This is a classic many-to-many relationship, handled with a separate enrollment association table that also stores the date a student enrolled.

The most important design decision: the Student model stores the face encoding as raw binary — a 128-float numpy array serialized to bytes. 𝗡𝗼 𝗿𝗮𝘄 𝗳𝗮𝗰𝗲 𝗶𝗺𝗮𝗴𝗲𝘀 𝗮𝗿𝗲 𝗲𝘃𝗲𝗿 𝘀𝗮𝘃𝗲𝗱 𝗮𝗻𝘆𝘄𝗵𝗲𝗿𝗲. This is a deliberate privacy-first choice.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟰 — 𝗕𝘂𝗶𝗹𝗱 𝘁𝗵𝗲 𝗔𝘂𝘁𝗵𝗲𝗻𝘁𝗶𝗰𝗮𝘁𝗶𝗼𝗻 𝗦𝘆𝘀𝘁𝗲𝗺 (𝗝𝗪𝗧 + 𝗥𝗼𝗹𝗲-𝗕𝗮𝘀𝗲𝗱 𝗔𝗰𝗰𝗲𝘀𝘀)

Security is not optional. I built the auth layer before any feature routes — because every route depends on knowing who is calling it and what role they have.

The system has two roles: 𝗮𝗱𝗺𝗶𝗻 and 𝘀𝘁𝘂𝗱𝗲𝗻𝘁, stored directly on the User record.

𝗣𝗮𝘀𝘀𝘄𝗼𝗿𝗱 𝗵𝗮𝘀𝗵𝗶𝗻𝗴 uses 𝗕𝗰𝗿𝘆𝗽𝘁 via the passlib library. Passwords are never stored in plain text — only the hash is saved to the database.

𝗝𝗪𝗧 𝘁𝗼𝗸𝗲𝗻𝘀 are issued on login. Each token carries the user’s ID and role, and expires after 24 hours. Every subsequent API request must include this token in the Authorization header.

𝗥𝗼𝘂𝘁𝗲 𝗽𝗿𝗼𝘁𝗲𝗰𝘁𝗶𝗼𝗻 is handled by FastAPI dependency injection. I created two reusable guard functions — one that enforces admin access, one that enforces student access. Any route just declares which guard it needs and FastAPI handles the rest automatically. This made it impossible to accidentally expose an admin endpoint to a regular student.

The system also auto-creates a default admin account on first startup — no manual database seeding required.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟱 — 𝗕𝘂𝗶𝗹𝗱 𝘁𝗵𝗲 𝗙𝗮𝗰𝗲 𝗘𝗻𝗰𝗼𝗱𝗶𝗻𝗴 𝗣𝗶𝗽𝗲𝗹𝗶𝗻𝗲

This was the most technically complex piece. The goal: take an image, detect the face, and produce a 128-number vector — called an 𝗲𝗻𝗰𝗼𝗱𝗶𝗻𝗴 — that uniquely represents that person’s face.

𝗣𝗿𝗶𝗺𝗮𝗿𝘆 𝗺𝗲𝘁𝗵𝗼𝗱 — 𝗱𝗹𝗶𝗯 𝘃𝗶𝗮 𝗳𝗮𝗰𝗲_𝗿𝗲𝗰𝗼𝗴𝗻𝗶𝘁𝗶𝗼𝗻: The face_recognition library (built on dlib) detects face locations in an image and computes a 128-dimension floating-point vector for each face found. This encoding is the mathematical “fingerprint” of a face. Two photos of the same person produce encodings with a very small Euclidean distance. Two different people produce a large distance. A threshold of 0.5 is used — faces within that distance are considered a match.

𝗧𝗵𝗲 𝗰𝗵𝗮𝗹𝗹𝗲𝗻𝗴𝗲: dlib requires C++ build tools to compile from source. Many environments don’t have them. Rather than making the whole system fail, I built a graceful fallback.

𝗙𝗮𝗹𝗹𝗯𝗮𝗰𝗸 𝗺𝗲𝘁𝗵𝗼𝗱 — 𝗢𝗽𝗲𝗻𝗖𝗩 𝗛𝗮𝗮𝗿 𝗖𝗮𝘀𝗰𝗮𝗱𝗲 + 𝗰𝗼𝗹𝗼𝗿 𝗵𝗶𝘀𝘁𝗼𝗴𝗿𝗮𝗺 𝗲𝗻𝗰𝗼𝗱𝗶𝗻𝗴: If face_recognition isn’t available, OpenCV’s Haar Cascade classifier detects the face region. That region is resized to a fixed size and analyzed channel-by-channel to build a 128-bin color histogram — a different kind of numerical fingerprint. It’s less accurate than dlib embeddings but keeps the system functional without any C++ dependencies.

Both methods produce a 128-dimension array, so storage, comparison, and matching work identically regardless of which method is used. The system detects which method is available at startup and uses it consistently throughout.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟲 — 𝗜𝗻𝘁𝗲𝗴𝗿𝗮𝘁𝗲 𝗬𝗢𝗟𝗢𝘃𝟴 𝗳𝗼𝗿 𝗣𝗲𝗿𝘀𝗼𝗻 𝗗𝗲𝘁𝗲𝗰𝘁𝗶𝗼𝗻

Face recognition alone has a problem: someone could hold up a printed photo and trick the system. 𝗬𝗢𝗟𝗢𝘃𝟴 adds a real-world validation layer — it confirms that an actual person is physically present in the camera frame before any face recognition is attempted.

YOLOv8 (the nano variant, optimized for speed) runs on every incoming camera frame and looks specifically for the “person” class. If no person is detected, face recognition is skipped entirely — saving compute and preventing the most obvious spoofing attack.

Like face_recognition, YOLOv8 is wrapped in a conditional import so the system starts cleanly and continues in degraded mode if the model isn’t available.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟳 — 𝗕𝘂𝗶𝗹𝗱 𝘁𝗵𝗲 𝗥𝗲𝗮𝗹-𝗧𝗶𝗺𝗲 𝗪𝗲𝗯𝗦𝗼𝗰𝗸𝗲𝘁 𝗞𝗶𝗼𝘀𝗸

This was the most exciting engineering challenge. The live attendance kiosk needs to receive a continuous stream of camera frames from the browser, run the full AI pipeline on each one, and send the result back instantly — all without the overhead of repeated HTTP requests.

𝗪𝗲𝗯𝗦𝗼𝗰𝗸𝗲𝘁𝘀 are the only sensible solution. They keep a persistent, two-way connection open between the browser and the server.

Here’s the flow that happens dozens of times per second:

1. Browser captures a webcam frame using react-webcam
2. Frame is encoded as a base64 JPEG string and sent over the WebSocket
3. Backend decodes the image and runs 𝗬𝗢𝗟𝗢𝘃𝟴 person detection
4. If a person is confirmed, runs face encoding on the frame
5. Loads all enrolled students’ stored encodings from the database
6. Compares using Euclidean distance to find the closest match
7. If a match is found within the tolerance threshold, records attendance and sends back the student’s name, confidence score, and face bounding box coordinates
8. Browser draws the bounding box overlay on a canvas and displays the name

The frontend throttles frame sending to approximately 10 frames per second to avoid overwhelming the backend while still feeling real-time to the user.

𝗠𝘂𝗹𝘁𝗶-𝗰𝗼𝘂𝗿𝘀𝗲 𝗰𝗼𝗻𝗳𝗹𝗶𝗰𝘁 𝗿𝗲𝘀𝗼𝗹𝘂𝘁𝗶𝗼𝗻 was also added: if a student is enrolled in two courses that both have active sessions at the same time, the system handles the selection intelligently rather than recording double attendance.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟴 — 𝗕𝘂𝗶𝗹𝗱 𝘁𝗵𝗲 𝗙𝗮𝘀𝘁𝗔𝗣𝗜 𝗥𝗘𝗦𝗧 𝗘𝗻𝗱𝗽𝗼𝗶𝗻𝘁𝘀

With the AI pipeline working, I built all the standard management endpoints that power the dashboards.

𝗘𝗻𝗱𝗽𝗼𝗶𝗻𝘁 𝗴𝗿𝗼𝘂𝗽𝘀: • 𝗔𝘂𝘁𝗵 𝗿𝗼𝘂𝘁𝗲𝘀 — register, login, get current user, update profile, upload/delete profile picture • 𝗔𝗱𝗺𝗶𝗻 𝗿𝗼𝘂𝘁𝗲𝘀 — full CRUD for students, courses, and attendance sessions; attendance reports with filtering by course or session • 𝗦𝘁𝘂𝗱𝗲𝗻𝘁 𝗿𝗼𝘂𝘁𝗲𝘀 — view own profile, enroll/unenroll from courses, view attendance history, register own face via webcam

FastAPI’s Pydantic integration made validation clean — each request body has a strict schema, and invalid requests are automatically rejected with clear error messages before they ever reach the database.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟵 — 𝗕𝘂𝗶𝗹𝗱 𝘁𝗵𝗲 𝗥𝗲𝗮𝗰𝘁 𝗙𝗿𝗼𝗻𝘁𝗲𝗻𝗱

The frontend is organized around three main views and a shared authentication context.

𝗔𝘂𝘁𝗵𝗲𝗻𝘁𝗶𝗰𝗮𝘁𝗶𝗼𝗻 is managed via React Context — the logged-in user’s data and JWT token are stored in context and localStorage, available to any component without prop drilling.

𝗔𝗣𝗜 𝗰𝗮𝗹𝗹𝘀 all go through a centralized Axios instance that automatically attaches the JWT token to every request — no component ever manually handles authorization headers.

𝗔𝗱𝗺𝗶𝗻 𝗗𝗮𝘀𝗵𝗯𝗼𝗮𝗿𝗱 — the largest component, organized into tabs: • Overview with live statistics — total students, courses, active sessions, face enrollment rate • Student management — add, edit, delete, course assignments, face registration via webcam • Course management — create, update, delete • Session management — start and stop attendance sessions per course • Attendance reports with course and session filtering

𝗦𝘁𝘂𝗱𝗲𝗻𝘁 𝗗𝗮𝘀𝗵𝗯𝗼𝗮𝗿𝗱 — the student-facing view: • Personal attendance rate per course shown as bar charts via Recharts • List of enrolled courses with per-course percentages • Available courses for self-enrollment • Webcam-based face registration — student takes a photo that gets sent to the backend for encoding

𝗟𝗶𝘃𝗲 𝗞𝗶𝗼𝘀𝗸 — connects to the WebSocket endpoint, streams webcam frames, receives recognition results, and draws bounding box overlays on a canvas. Shows “Recognized ✓” with the student name, or “Unknown Face” for unregistered individuals.

𝗗𝗲𝘀𝗶𝗴𝗻 𝘀𝘆𝘀𝘁𝗲𝗺 — a full glassmorphism CSS system with a dark theme, gradient accents, smooth hover transitions, and consistent spacing — all in vanilla CSS, no Tailwind dependency.

────────────────────────────────────

𝗦𝘁𝗲𝗽 𝟭𝟬 — 𝗗𝗲𝗽𝗹𝗼𝘆𝗺𝗲𝗻𝘁 𝗔𝗿𝗰𝗵𝗶𝘁𝗲𝗰𝘁𝘂𝗿𝗲

Local development runs two processes in parallel — the backend on port 8000 with hot reload, and the Vite dev server on port 5173 with HMR.

Production deployment uses a proper layered stack:

𝗚𝘂𝗻𝗶𝗰𝗼𝗿𝗻 + 𝗨𝘃𝗶𝗰𝗼𝗿𝗻 𝘄𝗼𝗿𝗸𝗲𝗿𝘀 → Multi-process ASGI serving 𝗡𝗴𝗶𝗻𝘅 → SSL termination, WebSocket proxy, static file serving 𝗗𝗼𝗰𝗸𝗲𝗿 → Reproducible Python + AI environment 𝗩𝗲𝗿𝗰𝗲𝗹 → CDN-backed React frontend deployment 𝗣𝗼𝘀𝘁𝗴𝗿𝗲𝗦𝗤𝗟 (prod) / 𝗦𝗤𝗟𝗶𝘁𝗲 (dev) → Persistent data storage

The most critical Nginx detail: 𝗪𝗲𝗯𝗦𝗼𝗰𝗸𝗲𝘁 connections require special proxy headers — Upgrade and Connection. Without them, the live kiosk silently fails behind Nginx with no obvious error.

𝗗𝗼𝗰𝗸𝗲𝗿 is especially important because dlib and YOLOv8 have complex native dependencies — C++ libraries and model weight files. Containerizing the backend means the exact same environment runs in development, staging, and production, eliminating environment-specific bugs entirely.

────────────────────────────────────

𝗖𝗵𝗮𝗹𝗹𝗲𝗻𝗴𝗲𝘀 𝗜 𝗛𝗶𝘁 𝗮𝗻𝗱 𝗛𝗼𝘄 𝗜 𝗦𝗼𝗹𝘃𝗲𝗱 𝗧𝗵𝗲𝗺

❌ 𝗱𝗹𝗶𝗯 𝘄𝗼𝗻’𝘁 𝗶𝗻𝘀𝘁𝗮𝗹𝗹 𝘄𝗶𝘁𝗵𝗼𝘂𝘁 𝗖++ 𝗯𝘂𝗶𝗹𝗱 𝘁𝗼𝗼𝗹𝘀 → Built the OpenCV histogram fallback that produces a compatible 128-dimension encoding. System gracefully degrades without breaking.

❌ 𝗪𝗲𝗯𝗦𝗼𝗰𝗸𝗲𝘁 𝗳𝗿𝗮𝗺𝗲𝘀 𝗮𝗿𝗿𝗶𝘃𝗶𝗻𝗴 𝗳𝗮𝘀𝘁𝗲𝗿 𝘁𝗵𝗮𝗻 𝗽𝗿𝗼𝗰𝗲𝘀𝘀𝗶𝗻𝗴 𝘀𝗽𝗲𝗲𝗱 → Added frame throttling on the frontend — send a frame every 100ms, not on every render cycle. The backend processes one frame per connection at a time.

❌ 𝗠𝘂𝗹𝘁𝗶𝗽𝗹𝗲 𝗮𝗰𝘁𝗶𝘃𝗲 𝘀𝗲𝘀𝘀𝗶𝗼𝗻𝘀 𝗰𝗮𝘂𝘀𝗶𝗻𝗴 𝗰𝗼𝗻𝗳𝘂𝘀𝗶𝗼𝗻 → Added multi-course conflict detection. If a student is in two courses with active sessions simultaneously, the system handles the selection intelligently.

❌ 𝗙𝗮𝗰𝗲 𝗲𝗻𝗰𝗼𝗱𝗶𝗻𝗴𝘀 𝗻𝗼𝘁 𝗽𝗼𝗿𝘁𝗮𝗯𝗹𝗲 𝗯𝗲𝘁𝘄𝗲𝗲𝗻 𝗱𝗹𝗶𝗯 𝗮𝗻𝗱 𝗢𝗽𝗲𝗻𝗖𝗩 → The encoding method is detected at runtime and used consistently. Mixing methods on a single deployment is avoided by design.

❌ 𝗝𝗪𝗧 𝘀𝘂𝗯 𝗳𝗶𝗲𝗹𝗱 𝗺𝘂𝘀𝘁 𝗯𝗲 𝗮 𝘀𝘁𝗿𝗶𝗻𝗴 𝗽𝗲𝗿 𝘀𝗽𝗲𝗰𝗶𝗳𝗶𝗰𝗮𝘁𝗶𝗼𝗻 → User ID is cast to a string when creating the token and back to an integer when verifying. A subtle bug that caused 401 errors until tracked down.

────────────────────────────────────

𝗪𝗵𝗮𝘁 𝗜’𝗱 𝗗𝗼 𝗗𝗶𝗳𝗳𝗲𝗿𝗲𝗻𝘁𝗹𝘆

1. 𝗦𝗲𝗽𝗮𝗿𝗮𝘁𝗲 𝘁𝗵𝗲 𝗔𝗜 𝘄𝗼𝗿𝗸𝗲𝗿 — run face recognition in a dedicated async process to avoid blocking the event loop under heavy load
2. 𝗔𝗱𝗱 𝗥𝗲𝗱𝗶𝘀 — for session state caching instead of hitting the database on every WebSocket frame
3. 𝗔𝗱𝗱 𝗹𝗶𝘃𝗲𝗻𝗲𝘀𝘀 𝗱𝗲𝘁𝗲𝗰𝘁𝗶𝗼𝗻 — blink detection or head movement to prevent photo spoofing more robustly
4. 𝗠𝘂𝗹𝘁𝗶-𝗰𝗮𝗺𝗲𝗿𝗮 𝘀𝘂𝗽𝗽𝗼𝗿𝘁 — one WebSocket connection per camera, all feeding into a shared session

────────────────────────────────────

𝗖𝗹𝗼𝘀𝗶𝗻𝗴 𝗧𝗵𝗼𝘂𝗴𝗵𝘁𝘀

This project touched every layer of modern software: database design, secure authentication, computer vision, real-time communication, UI development, and production deployment. Each layer had its own challenges, and solving them end-to-end gave me a much deeper appreciation for how complex production systems actually work.

If you’re a developer looking to go beyond CRUD apps, I’d strongly recommend building something that involves real-time data and AI — it forces you to think about performance, reliability, and user experience in ways that simple request/response systems never do.

Feel free to reach out if you have questions about any specific part of the architecture!

────────────────────────────────────

Python #FastAPI #ReactJS #ComputerVision #YOLOv8 #FaceRecognition #WebSocket #FullStack #EdTech #SoftwareEngineering