Home
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. It leverages the high-accuracy InsightFace/ArcFace machine learning model for face recognition, achieving over 99% accuracy. The system provides a robust solution for automated attendance through a webcam, supplemented by a cross-device QR code synchronization feature for enhanced flexibility.
This project, currently at version 2.0, is production-ready and incorporates significant security and architectural improvements. It features a modular structure, standardized API responses, comprehensive error handling, and secure configuration management using environment variables. The administrative backend provides tools for employee management, attendance monitoring, and report generation.
Sources: README.md:3-6, CHANGELOG.md:15-17, CONTRIBUTING.md:43-47
Key Features
The system offers a range of features designed for modern, efficient attendance management.
| Feature | Description |
|---|---|
| Face Recognition | Utilizes the InsightFace/ArcFace model for face recognition with 99%+ accuracy. |
| QR Sync | Allows cross-device attendance synchronization via a unique, auto-refreshing QR code. |
| Camera Lock | Prevents multiple detections of the same face to ensure data integrity. |
| Real-time Dashboard | An admin dashboard to view live attendance status, employee data, and system statistics. |
| CSV Export | Enables exporting attendance logs into CSV format for reporting and analysis. |
| Enhanced Security | Implements environment variables for secrets, input validation, and structured error handling. |
| Cloudflare Tunnel | Provides secure HTTPS access for the application without requiring complex port forwarding. |
Sources: README.md:10-17, CHANGELOG.md:58-69
System Architecture
The application is built on a modular Flask backend, a vanilla JavaScript frontend, and a MySQL database. The architecture emphasizes a clear separation of concerns, with dedicated modules for face recognition, QR synchronization, database operations, and API logic.
Sources: CLEANUP_REPORT.md:52-68, CONTRIBUTING.md:72-88
This diagram illustrates the high-level architecture and the interaction between the main components of the system.
Technology Stack
The project utilizes a modern and robust technology stack for its backend, frontend, and machine learning components.
| Layer | Technology |
|---|---|
| Backend | Flask, PyMySQL, OpenCV, scikit-learn |
| Frontend | HTML5, CSS3, Bootstrap 5, Vanilla JavaScript |
| Database | MySQL 8.0+ |
| ML | InsightFace/ArcFace |
| Security | python-dotenv, Flask-WTF, Flask-Limiter |
| Infrastructure | Cloudflare Tunnel |
Sources: README.md:21-28, INSTALLATION.md:143-153
Core Components
The codebase is organized into several key Python files, each with a distinct responsibility. This modular structure was refined in version 2.0 to improve maintainability.
| File | Purpose |
|---|---|
app.py | The main Flask application, handling routes, QR sync logic, and integrating other modules. |
config.py | Manages application and database configuration, loading values from .env. |
database.py | Handles database connection and initialization of tables. |
models.py | Defines the data models for the application (e.g., User, Attendance). |
helpers.py | Provides functions for standardizing API responses. |
validators.py | Contains decorators for validating incoming API request data. |
face_recognition_insightface.py | Encapsulates all logic related to face detection and recognition using the InsightFace model. |
qr_sync.py | Manages the creation, verification, and lifecycle of QR codes for cross-device sync. |
camera_lock.py | Implements logic to control camera access and prevent multiple detections. |
Sources: CLEANUP_REPORT.md:53-62, CONTRIBUTING.md:91-96, SECURITY.md:50-53, 62-65
Data Flow and Processes
QR Code Synchronization Flow
The QR sync process enables users to authenticate on a primary device (e.g., a laptop) by scanning a QR code with a secondary device (e.g., a mobile phone), which is necessary for camera access on mobile browsers that require HTTPS.
Sources: static/openapi.yaml:31-99, CHANGELOG.md:73-78
Admin Dashboard Data Loading
The admin dashboard is a single-page application that loads data dynamically from the backend API to provide real-time statistics.
API Endpoints
The system exposes a RESTful API for frontend interactions and administrative tasks. The API is documented using the OpenAPI 3.0 standard.
| Method | Endpoint | Description | Tag |
|---|---|---|---|
| GET | /auth | Renders the QR authentication page. | QR Authentication |
| GET | /api/qr_sync_status | Polls the server to check if a QR code has been scanned. | QR Authentication |
| POST | /api/accept_qr_sync | Confirms the QR sync from the mobile device. | QR Authentication |
| GET | /web_attendance | Renders the main web attendance page with the camera feed. | Attendance |
| POST | /mark_attendance_mobile | Submits an attendance record from a mobile device. | Attendance |
| GET | /api/employees | Retrieves a list of all employees. | Employees |
| POST | /api/employees | Adds a new employee and their training photos. | Employees |
| GET | /admin/dashboard | Renders the main admin dashboard. | Admin |
| POST | /api/train_model | Triggers the re-training of the face recognition model. | Admin |
| GET | /health | A health check endpoint to monitor system status. | System |
Sources: static/openapi.yaml
Configuration
Application configuration is managed securely through environment variables using a .env file, which is loaded by config.py. This practice prevents hardcoding sensitive credentials in the source code.
| Variable | Description | Example |
|---|---|---|
DB_HOST | The hostname of the MySQL database server. | localhost |
DB_USER | The username for the MySQL database. | root |
DB_PASSWORD | The password for the MySQL database user. | yourpassword |
DB_NAME | The name of the database to use. | smart_absen |
SECRET_KEY | A secret key for signing session cookies. | your-secret-key |
FLASK_ENV | The environment mode for Flask. | production |
PORT | The port on which the application will run. | 5001 |
FACE_CONFIDENCE | The minimum confidence score to accept a face match. | 0.6 |
Sources: README.md:104-115, SECURITY.md:7-10, INSTALLATION.md:231-246
Security & Quality
Version 2.0 introduced a major overhaul focused on security and code quality.
- Environment Variables: All sensitive data, such as database credentials and secret keys, are managed via a
.envfile, separating configuration from code. - Input Validation: Decorators in
validators.pyare used to sanitize and validate all data submitted to API endpoints, protecting against common vulnerabilities like SQL injection and XSS. - Standardized API Responses: A consistent JSON structure for all API responses is enforced by
helpers.py, simplifying frontend integration and error handling. - Structured Logging: The application uses a rotating file logger to write structured logs to
logs/app.log, which aids in debugging and auditing. - Error Handling: Custom, user-friendly error pages are implemented for common HTTP errors (404, 500, 403) to prevent information leakage.
Sources: SECURITY.md:4-48, CHANGELOG.md:17-31