Architectural Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Smart Absen Face Recognition system is a Flask-based web application designed for intelligent employee attendance tracking. Its architecture is centered around a monolithic backend that serves a traditional multi-page web application, enhanced with client-side JavaScript for real-time features. The system leverages the high-accuracy InsightFace/ArcFace model for face recognition, a MySQL database for data persistence, and a QR code mechanism for cross-device synchronization.
The architecture was significantly updated in Version 2.0 to improve security, modularity, and maintainability. Key improvements include the adoption of environment variables for configuration, standardized API responses, input validation, and a more structured frontend with template inheritance. The system is designed for local deployment but includes support for secure public access via Cloudflare Tunnels.
Sources: README.md, CHANGELOG.md:12-33
Core Components
The application is structured into several key Python modules and directories, promoting a separation of concerns. The main components are organized to handle web requests, database interactions, business logic, and frontend rendering distinctly.
Sources: CLEANUP_REPORT.md:54-72, CONTRIBUTING.md:63-87
This diagram illustrates the high-level component architecture of the Smart Absen system.
Sources: CLEANUP_REPORT.md:54-72, CONTRIBUTING.md:63-87
Key Files and Their Responsibilities
| File/Directory | Purpose |
|---|---|
app.py | The main Flask application entry point. It defines URL routes, handles web requests, and integrates all other modules. |
config.py | Manages application and database configurations, loading sensitive data from .env files. |
database.py | Handles database connection and initialization, including automatic table creation. |
models.py | Defines the data models for the application, such as employees and attendance. |
helpers.py | Provides utility functions for creating standardized JSON API responses. |
validators.py | Contains decorators for validating incoming API request data to ensure data integrity. |
qr_sync.py | Implements the logic for cross-device synchronization using QR codes. |
face_recognition_insightface.py | Encapsulates the face detection and recognition logic using the InsightFace model. |
templates/ | Contains all Jinja2 HTML templates for rendering the user interface. |
static/ | Stores static assets like CSS stylesheets, JavaScript files, and images. |
Sources: README.md:41-69, CONTRIBUTING.md:89-94, SECURITY.md:32-54
Technology Stack
The project is built on a combination of Python for the backend, standard web technologies for the frontend, and a powerful machine learning library for its core feature.
| Layer | Technology | Purpose |
|---|---|---|
| Backend | Flask, PyMySQL, OpenCV | Web framework, database driver, and computer vision. |
| Frontend | HTML5, CSS3, Bootstrap 5, Vanilla JS | User interface structure, styling, and client-side interactivity. |
| Database | MySQL 8.0+ | Persistent storage for employee and attendance data. |
| ML | InsightFace/ArcFace, scikit-learn | High-accuracy face recognition and classification. |
| Security | python-dotenv, Flask-WTF | Secure configuration and form protection. |
| Deployment | Cloudflare Tunnel, Docker | Secure public access and containerization. |
Sources: README.md:19-27, INSTALLATION.md:12-20, 110-122
API Architecture
The application exposes a RESTful API for various functionalities, including attendance, employee management, and system health checks. The API is documented using the OpenAPI 3.0 standard.
Sources: static/openapi.yaml
Key API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/qr_sync_status | Polling endpoint for clients to check if a QR code has been scanned. |
POST | /api/accept_qr_sync | Used by the mobile device to confirm a QR scan and authorize the desktop session. |
POST | /mark_attendance_mobile | Submits an attendance record from a mobile device, including image data. |
GET | /api/employees | Retrieves a list of all registered employees. |
POST | /api/employees | Adds a new employee to the database. Requires admin authentication. |
POST | /api/train_model | Triggers the re-training of the face recognition model. Requires admin authentication. |
GET | /health | A health check endpoint to monitor the status of the application and its dependencies. |
Sources: static/openapi.yaml
QR Authentication Flow
The QR sync feature allows a user to authenticate a session on a desktop computer by scanning a QR code with their mobile phone. This is essential for enabling webcam access on mobile browsers, which often require a secure context (HTTPS).
This sequence diagram shows the interaction between the user's desktop, their mobile device, and the server during QR code authentication.
Sources: static/openapi.yaml:31-100
Frontend Architecture
The frontend is a multi-page application rendered by Flask using Jinja2 templates. A significant architectural feature is the use of template inheritance to maintain a consistent layout across the application.
Sources: CHANGELOG.md:21-25
Template Inheritance
A base template (base.html) defines the main HTML structure, and specialized templates like admin_base.html extend it to create layouts for specific sections of the site. Content pages then extend these base layouts.
This diagram shows the Jinja2 template inheritance structure.
Admin Dashboard Structure
The admin dashboard (admin_dashboard.html) is designed as a single-page interface that loads different management sections (Employees, Attendance, Reports) into <iframe> elements. This approach contains each section's functionality within its own page while providing a seamless user experience without full page reloads for navigation. Client-side JavaScript is used to switch between sections by changing the src of the iframes and to fetch real-time statistics from the /admin/api/stats endpoint.
Sources: templates/admin_dashboard.html:624-659, 730-747
Security Architecture
Version 2.0 of the application introduced a major overhaul of its security posture. The architecture now incorporates several best practices to protect the application and its data.
| Feature | Implementation | Benefit |
|---|---|---|
| Environment Variables | A .env file, read by config.py, stores all secrets. | Prevents hardcoding credentials in the source code. |
| Input Validation | Decorators in validators.py check incoming API data. | Protects against invalid data entry and potential injection attacks. |
| Standardized API Responses | The helpers.py module ensures all API responses follow a consistent format. | Simplifies client-side error handling and integration. |
| Structured Logging | A rotating file handler logs application events to logs/app.log. | Provides an audit trail and aids in debugging production issues. |
| Error Handling | Custom error pages (templates/error.html) and global error handlers in app.py. | Prevents sensitive information leakage and improves user experience. |
Sources: SECURITY.md:4-54, CHANGELOG.md:14-20
Conclusion
The architecture of the Smart Absen system is that of a modern, modular Flask application. It effectively separates concerns between the backend logic, frontend rendering, and data persistence layers. The integration of a high-accuracy ML model for face recognition and a QR-based synchronization system demonstrates a practical approach to solving real-world attendance tracking challenges. The enhancements in version 2.0, particularly around security and code structure, have made the codebase more robust, maintainable, and production-ready.
Sources: README.md, CLEANUP_REPORT.md, CHANGELOG.md