Project Structure

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• CLEANUP_REPORT.md
• INSTALLATION.md
• CHANGELOG.md
• SECURITY.md
• setup_docs.sh
• static/openapi.yaml
• templates/admin_base.html
• [templates/admin_dashboard.html](https://github.com/Fahri-Hilm/Smart_Absen_Facerecognation-2025-Kelompok4/blob /main/templates/admin_dashboard.html)

The Smart Absen project is organized into a modular and maintainable structure, centered around a Flask backend. The architecture emphasizes a clear separation of concerns, with distinct layers for the web application, business logic, data models, configuration, and frontend assets. This design was refined in version 2.0 to enhance security, code quality, and readiness for production environments.

The structure facilitates parallel development, with backend developers focusing on Python logic and API endpoints, while frontend developers work on Jinja2 templates and static assets. Key architectural improvements include the introduction of helper modules, validation decorators, and a standardized API response format, making the codebase cleaner and more robust.

Sources: README.md:31-69, CONTRIBUTING.md:65-88, CLEANUP_REPORT.md:58-79, CHANGELOG.md:16-41

High-Level Directory Layout

The project's root directory contains core application files, configuration, documentation, and subdirectories for templates, static assets, logs, and ML models.

This diagram illustrates the primary directories and their roles within the project.

Key Directories

Directory	Purpose
(root)	Contains the main Flask application (app.py) and core Python modules.
templates/	Holds all Jinja2 HTML templates for the user interface and admin panel.
static/	Stores static assets like CSS stylesheets, JavaScript files, and images. Also contains the openapi.yaml for API docs.
assets/	Contains machine learning models, such as haarcascade_frontalface_default.xml and the InsightFace model.
logs/	Stores application logs, configured with a rotating file handler.
docs/	Contains all technical and user documentation for the project.
Attendance/	Default location for exported CSV attendance logs.

Sources: README.md:31-69, CONTRIBUTING.md:65-88, CLEANUP_REPORT.md:58-79

Backend Architecture

The backend is built with Flask and follows a modular pattern. Core logic is separated into distinct files, each with a specific responsibility.

This diagram shows the interaction between the main backend components.

Core Python Files

File	Description
app.py	The main application entry point. It defines all URL routes, handles requests, integrates face recognition and QR sync logic, and manages application-level concerns like error handling and logging.
config.py	Manages application and database configuration. It loads sensitive values from a .env file to keep secrets out of the codebase.
database.py	Handles database initialization. It is responsible for creating the necessary tables when the application starts for the first time.
models.py	Defines the data models for the application, such as User and Attendance, which map to database tables.
helpers.py	Provides utility functions, most notably api_response, which standardizes the structure of all JSON responses from the API.
validators.py	Contains decorator functions (@validate_json, @validate_employee_data) used to validate incoming request data before it reaches the route logic.
qr_sync.py	Encapsulates the logic for cross-device synchronization via QR codes.
face_recognition_insightface.py	Contains the core logic for face detection and recognition using the InsightFace model.
camera_lock.py	Manages camera access to prevent multiple detections of the same face.

Sources: README.md:32-40, CONTRIBUTING.md:84-88, CLEANUP_REPORT.md:60-68, SECURITY.md:30-57

Frontend Architecture

The frontend is built with HTML5, Bootstrap 5, and vanilla JavaScript, using the Jinja2 templating engine provided by Flask. The structure is designed to be DRY (Don't Repeat Yourself) through template inheritance.

Template Inheritance

A base template system is used to maintain a consistent layout across the application.

• base.html: The main base template (not provided in context, but inferred).
• admin_base.html: Extends base.html and provides the common layout for all admin-facing pages, including a sidebar menu and main content area.
• Specific Pages (e.g., admin_dashboard.html, admin_reports.html): These pages either extend admin_base.html or are loaded into <iframe> elements within the admin dashboard, creating a modular, single-page application feel.

This diagram shows the inheritance and composition model of the admin templates.

Static Assets

• CSS: Styles are centralized in static/css/theme.css, which defines a consistent theme (colors, fonts, etc.) for the application.
• JavaScript: Logic is separated into dedicated files, such as static/js/capture-simple.js for face capture, which is a significant improvement from embedding JS directly in HTML.
• API Specification: The static/openapi.yaml file is stored here to be served by the application for the Swagger UI documentation.

Sources: README.md:43-46, CHANGELOG.md:28, setup_docs.sh:15

API and Documentation Structure

The project exposes a RESTful API for frontend interactions and provides comprehensive documentation via Swagger UI.

API Endpoints

The API is organized by resource tags, such as QR Authentication, Attendance, and Employees.

Method	Endpoint	Description	Tag
GET	/api/qr_sync_status	Polling endpoint to check if a QR code has been scanned.	QR Authentication
POST	/api/accept_qr_sync	Accepts QR sync verification from a mobile device.	QR Authentication
POST	/mark_attendance_mobile	Submits attendance from a mobile device with a captured face image.	Attendance
GET	/api/get_attendance_data	Retrieves attendance records with optional filters.	Attendance
GET	/api/employees	Retrieves a list of all employees.	Employees
POST	/api/employees	Adds a new employee (admin-only).	Employees
GET	/health	A health check endpoint to monitor system status.	System

Sources: static/openapi.yaml, README.md:129-137

API Documentation Flow

The setup_docs.sh script copies the OpenAPI specification to the static folder, which is then served by a Flask route to render the Swagger UI.

This diagram shows how the API documentation is generated and served.

Configuration and Environment

Configuration is managed securely and flexibly using environment variables, loaded via python-dotenv.

• .env.example: A template file that lists all required environment variables. Developers copy this to .env and fill in their local values.
• .env: The actual configuration file, which is not committed to version control (as specified by .gitignore).
• config.py: This script reads the .env file and exposes the configuration values to the rest of the Flask application.

Key Environment Variables

Variable	Purpose	Example
DB_HOST	MySQL database host.	localhost
DB_USER	MySQL username.	root
DB_PASSWORD	MySQL password.	yourpassword
DB_NAME	The name of the application's database.	smart_absen
SECRET_KEY	A secret key for signing session cookies.	your-secret-key
FLASK_ENV	The Flask environment.	production or development
PORT	The port the application runs on.	5001

Sources: README.md:108-120, SECURITY.md:5-15, INSTALLATION.md:204-219

Conclusion

The project structure of Smart Absen is well-defined, clean, and production-oriented. By separating concerns into backend logic, frontend templates, static assets, configuration, and documentation, the codebase is highly maintainable and scalable. The architectural decisions, such as using environment variables, standardizing API responses, and implementing template inheritance, reflect best practices for modern web application development. This organized structure was a key outcome of the v2.0 refactoring, significantly improving code quality and security.

Sources: CLEANUP_REPORT.md:82-99, CHANGELOG.md:16-41