Data Models

Relevant source files

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

• models.py
• static/openapi.yaml
• INSTALLATION.md
• templates/admin_database.html
• templates/admin_attendance.html
• templates/admin_reports.html

The data models are the structural backbone of the Smart Absen application, defining how information about employees, attendance, and system activities is stored and managed. These models are implemented as Python classes in models.py and interact with a MySQL database named absensi_karyawan_db. They provide a logical layer for all Create, Read, Update, and Delete (CRUD) operations, ensuring data consistency and integrity.

The core models are Employee, Attendance, and ActivityLog, which correspond to the main database tables. These models are used throughout the application, from handling API requests to rendering data in the admin dashboard. The API schemas, defined in openapi.yaml, are based on these models but sometimes use different field names, which is an important consideration for developers.

Sources: models.py, INSTALLATION.md:91, static/openapi.yaml

Database Schema

The application utilizes a relational database schema to link employees to their attendance records and activity logs. The primary tables are employees, attendance, and activity_log (referred to as system_logs in some parts of the admin interface). There is also an admins table for managing admin users.

The diagram below illustrates the relationships between the main entities.

This Entity-Relationship diagram shows the core tables in the database. An employee can have multiple attendance records and multiple activity logs.

Sources: models.py, INSTALLATION.md:128-135, templates/admin_database.html:260-318

Core Data Models

The application's logic is built around three primary model classes defined in models.py.

Sources: models.py

Employee Model

The Employee class manages all data related to employees. It is used for adding, retrieving, and deleting employee records.

This class diagram shows the static methods available in the Employee model for database interactions.

Sources: models.py:11-87

Fields

The employees table contains detailed information about each employee.

Field	Type	Description	Source
id	INT	Primary key for the employee.	static/openapi.yaml:263
nik	VARCHAR	Unique National Identity Number.	models.py:16, static/openapi.yaml:264
name	VARCHAR	Full name of the employee.	models.py:16, static/openapi.yaml:265
bagian	VARCHAR	Department or division of the employee.	models.py:16
email	VARCHAR	Employee's email address.	models.py:15
phone	VARCHAR	Employee's phone number.	models.py:15
gender	VARCHAR	Gender of the employee.	models.py:15
address	TEXT	Home address of the employee.	models.py:15
position	VARCHAR	Job title or position.	models.py:16, static/openapi.yaml:266
status	VARCHAR	Employment status (e.g., 'aktif').	models.py:16
hire_date	DATE	The date the employee was hired.	models.py:16
created_at	DATETIME	Timestamp of when the record was created.	static/openapi.yaml:268

Key Methods

Method	Description	Source
add_employee(...)	Adds a new employee to the database with comprehensive details.	models.py:14-27
get_employee_by_nik(nik)	Retrieves a single employee's data using their NIK.	models.py:41-49
get_all_employees()	Fetches a list of all employees, ordered by name.	models.py:52-59
delete_employee(employee_id)	Deletes an employee and all their associated attendance and activity log records.	models.py:65-87

Attendance Model

The Attendance class is responsible for managing employee check-in and check-out records. It includes logic to either create a new daily record or update an existing one.

This class diagram outlines the methods for managing attendance records.

Sources: models.py:90-222

Fields

The attendance table stores daily clock-in and clock-out times.

Field	Type	Description	Source
id	INT	Primary key for the attendance record.	static/openapi.yaml:274
employee_id	INT	Foreign key linking to the employees table.	models.py:94, static/openapi.yaml:275
tanggal	DATE	The date of the attendance record.	models.py:94
jam_masuk	TIME	The time the employee clocked in.	models.py:94
jam_pulang	TIME	The time the employee clocked out.	models.py:94
total_jam_kerja	TIMEDELTA	The calculated duration between clock-in and clock-out.	models.py:121

Logic Flow: add_or_update_attendance

This method contains the core logic for recording attendance. It prevents duplicate daily entries by checking if a record for the employee and date already exists.

This flowchart shows the decision process for adding or updating an attendance record.

Sources: models.py:94-142

ActivityLog Model

The ActivityLog class provides a simple way to log significant events in the system, such as employee creation or attendance marking. This is useful for auditing and debugging. In the admin panel, this table is referred to as system_logs.

This class diagram shows the methods for adding and retrieving activity logs.

Sources: models.py:225-252, templates/admin_database.html:294

Fields

The activity_log table stores a history of system events.

Field	Type	Description	Source
id	INT	Primary key for the log entry.	Inferred
employee_id	INT	Foreign key linking to the employee involved in the activity.	models.py:229
activity_type	VARCHAR	The type of activity being logged (e.g., 'ATTENDANCE_IN').	models.py:229
description	TEXT	A detailed description of the event.	models.py:229
created_at	DATETIME	Timestamp of when the log was created.	models.py:243

API Schema Representation

The data models are exposed through the application's API, as defined in static/openapi.yaml. These schemas are used for request and response validation.

Note: There are naming inconsistencies between the Python models (models.py) and the API schemas (openapi.yaml). For example, bagian in the model is department in the API, and tanggal is date.

Sources: static/openapi.yaml:260-293

API Schemas

The table below summarizes the key data structures as defined for the API.

Schema	Field	Type	Description
Employee	id	integer	Employee ID
	nik	string	Employee NIK
	name	string	Employee Name
	position	string	Employee Position
	department	string	Employee Department
	created_at	string (date-time)	Creation timestamp
Attendance	id	integer	Attendance record ID
	employee_id	integer	Employee ID
	employee_name	string	Employee Name
	date	string (date)	Attendance date
	time_in	string (time)	Clock-in time
	time_out	string (time)	Clock-out time
	status	string	Attendance status (e.g., hadir, telat)

Sources: static/openapi.yaml:261-285

Summary

The data models in models.py form a crucial abstraction layer over the MySQL database. The Employee, Attendance, and ActivityLog classes encapsulate all database logic, providing clear, reusable methods for data manipulation. While the database schema is straightforward, developers should be aware of the naming differences between the Python models and their corresponding API schemas in openapi.yaml to ensure smooth integration between the frontend and backend.