Ai-Face-recognition-Attendance-system: The Face Scan That Becomes a Web App
A FastAPI attendance system that turns webcam frames into check-ins and check-outs, stores facial embeddings in MySQL, and keeps the stack simpler than you would expect.
- This repo treats biometric attendance as ordinary web application design, not as a special-purpose hardware system.
- Its biggest simplification is architectural: FastAPI, MySQL, JWT, and serialized face encodings do the job without a vector database.
- Attendance is modeled as a state transition, which lets the first scan and second scan mean different things on the same day.
- The result is pragmatic and constrained, but that is exactly why it feels deployable for small and mid-size teams.
Face recognition usually gets sold as spectacle. This repo uses it as plumbing. A browser webcam frame becomes a JSON payload, a matching routine finds the employee, and the database decides whether this is a check-in or a check-out.
That is the interesting move. The system does not ask you to adopt a heavy biometric platform or a custom client app. It behaves like a normal FastAPI service with a single intelligent step in the middle.
The punch-card, reborn as a web request
The workflow is straightforward enough to fit in one breath: capture a frame in the browser, send it as Base64, decode it on the server, compare the face embedding, then write an attendance row. That makes the app feel less like a lab demo and more like a thin operational layer over a familiar business process.
Face recognition-based attendance system using Python and OpenCV.
Why this stack is the point
The repo uses the kind of stack a small team can actually run: FastAPI, SQLAlchemy, Pydantic, JWT, bcrypt, Docker, and MySQL. Nothing exotic is hiding behind the curtain.
| Approach | Hardware required | Setup complexity | User friction | Scale fit | Best fit |
|---|---|---|---|---|---|
| Manual logs | None | Very low | High | Any size, but error-prone | Tiny teams and low stakes |
| RFID or card system | Reader and cards | Low to medium | Medium | Good for standard offices | Access control with simple identity |
| This repo | Webcam and browser | Medium | Low | Small to mid-size deployments | Attendance with low operational overhead |
| Heavy commercial biometrics | Dedicated devices and licensing | High | Low | Large enterprise | Centralized, vendor-managed security |
The recognition engine is intentionally simple
In app/recognition.py, the project uses the familiar 128-dimensional face embedding pattern from face_recognition, then compares known and unknown faces with Euclidean distance. The result is a nearest-match decision wrapped in a confidence score that is easier for a human to read.
That simplicity matters because the project is trying to operationalize recognition, not invent a new model. It is a production-shaped wrapper around an established technique.
MySQL is doing more than storage
The data model is where the repo stops looking like a demo. Employee encodings are stored as serialized text, attendance rows use a unique constraint on employee and date, and inactive employees are soft-deleted with an is_active flag.
That is a sensible set of tradeoffs. It preserves history, avoids recomputing embeddings on every request, and keeps same-day attendance behavior explicit instead of magical.
What the database is really tracking
- Identity stays stable because the face encoding is stored once and reused.
- Daily attendance stays singular because each employee can only have one row per date.
- Lifecycle stays reversible because inactive records are preserved instead of deleted.
- The system can treat first scan and second scan as different states without extra hardware.
Why the startup path matters
The FastAPI lifespan pattern gives the app a real service boundary. On startup, it verifies the database, creates tables, and seeds a default admin, which makes the first run feel intentional instead of improvised.
That matters more than it sounds. A lot of open-source biometric projects stop at the prototype. This one does at least enough bootstrapping to suggest how it would behave in deployment.
Security is basic, but disciplined
The auth layer is not trying to be an identity platform. It uses JWT, protected dependencies, and a superadmin boundary for sensitive actions, which is the right size for a small attendance service.
| Control | What it protects | What it does well | What it does not solve |
|---|---|---|---|
| JWT auth | Session access | Keeps endpoints authenticated | Does not replace enterprise identity |
| Admin dependencies | Administrative routes | Separates everyday use from management | Does not add fine-grained policy by itself |
| Superadmin boundary | High-risk actions | Prevents casual privilege escalation | Still needs operational discipline |
| Soft deletes | Employee lifecycle | Preserves records after deactivation | Does not handle broader compliance needs |
Where this sits in the market
Compared with manual logs and RFID cards, the repo removes a repeated human task. Compared with heavy commercial biometrics, it removes a lot of vendor dependence. That is its niche: ordinary software discipline applied to a biometric workflow.
| Option | Why teams choose it | Why teams outgrow it |
|---|---|---|
| Manual attendance | No hardware and almost no setup | Slow, lossy, and easy to falsify |
| RFID cards | Cheap and familiar | Cards are shareable and still require hardware |
| This repo | Low-friction webcam workflow with simple web ops | Matching and storage choices will not scale forever |
| Commercial biometrics | Managed infrastructure and support | Cost, lock-in, and less control over the data model |
The limitation is also clear. In-memory matching and serialized encodings are pragmatic for small deployments, but they are not a long-term answer for very large populations. The repo accepts that constraint instead of pretending it does not exist.
The tradeoffs are the story
This project is compelling because it makes the right compromises for its target use case. It gives you a biometric attendance system that feels like a web app, behaves like a state machine, and avoids unnecessary infrastructure while still looking production-minded.