Database Models & Entities
Relevant source files
The following files were used as context for generating this wiki page:
- Part1/API/src/main/java/com/example/api/model/Assignment.java
- Part1/API/src/main/java/com/example/api/model/Department.java
- Part1/API/src/main/java/com/example/api/model/Employee.java
- Part1/API/src/main/java/com/example/api/entity/AppUser.java
- Part1/API/src/main/resources/api-spec.yaml
- Part1/API/src/main/java/com/example/api/repository/EmployeeRepository.java
- Part1/API/src/main/java/com/example/api/repository/DepartmentRepository.java
The SafeDispatch HQ Administration API utilizes a relational database schema managed via Jakarta Persistence (JPA). The data model is designed to represent the organizational structure of a logistics company, focusing on employees, their departmental affiliations, and administrative security users.
The core architecture follows a standard tiered approach where entities define the database schema, while JPA repositories handle data access. The relationship between employees and departments is managed through a central junction entity, allowing for complex assignments that include specific roles and access levels.
Core Domain Models
The domain model consists of three primary entities: Employee, Department, and Assignment. These entities form the backbone of the HR management system.
Employee Entity
The Employee entity represents a staff member within the organization. It stores personal details, contractual information, and compensation data. It also serves a secondary role in identifying the user's functional rank (e.g., ROLE_HR or ROLE_MANAGER) for business logic purposes.
Sources: Employee.java:10-82, api-spec.yaml:24-52
Department Entity
The Department entity defines organizational units. Key constraints include a requirement for a positive budget value. It maintains a bidirectional relationship with assignments, allowing the system to track all staff assigned to a specific location or unit.
Sources: Department.java:8-63, api-spec.yaml:54-73
Assignment Entity
Assignment acts as a relational bridge between Employee and Department. Unlike a simple join table, it contains metadata about the relationship, such as the specific role the employee performs within that department and their technical access level.
Sources: Assignment.java:6-58, api-spec.yaml:75-95
Entity Relationships
The system implements a One-to-Many relationship from both Employee and Department toward the Assignment entity. This effectively creates a Many-to-Many relationship between employees and departments while allowing for historical or multi-role tracking.
Entity Relationship Diagram
The following diagram illustrates the cardinality and primary connections between the core database entities.
The diagram shows that while an Employee or Department can exist independently, an Assignment requires a valid foreign key reference to both.
Sources: Employee.java:29-30, Department.java:21-22, Assignment.java:11-18
Model Specifications and Constraints
The following table summarizes the data fields, types, and constraints applied to the primary entities as defined in the source code and API specifications.
| Entity | Field | Type | Constraints | Description |
|---|---|---|---|---|
| Employee | id | Long | Primary Key, Identity | Unique identifier. |
email | String | Valid email format required. | ||
contractType | String | @NotNull | E.g., FULL_TIME, PART_TIME. | |
salary | Integer | - | Annual compensation. | |
| Department | budget | Integer | @Positive | Financial allocation; must be > 0. |
location | String | - | Physical site (e.g., Leicester). | |
| Assignment | employee | Employee | ManyToOne, Non-null | Reference to Employee. |
department | Department | ManyToOne, Non-null | Reference to Department. | |
accessLevel | String | - | Security clearance level (e.g., LEVEL_2). |
Sources: Employee.java:14-41, Department.java:11-22, Assignment.java:11-22, api-spec.yaml:24-95
Security Entities
Separate from the HR domain models, the system includes an AppUser entity specifically for authentication and authorization through Spring Security.
AppUser Entity
AppUser handles credentials for HQ administrators. It is decoupled from the Employee entity to ensure that administrative access is managed independently of personnel records.
- username: Unique identifier for login.
- password: Hashed credential.
- role: Defined roles such as "HR" or "MANAGER" which dictate API access permissions.
Sources: AppUser.java:5-30, SecurityConfig.java:45-50
Data Access Logic
Relationships are navigated using JPA Query Language (JPQL) within the repository layer. The EmployeeRepository and DepartmentRepository define how data is fetched across these entity boundaries.
Cross-Entity Query Flow
This sequence shows how the repository layer resolves the relationship between departments and employees via the Assignment entity.
Summary
The SafeDispatch database structure is built on a clear separation between HR domain models (Employee, Department) and security entities (AppUser). By utilizing the Assignment entity as a metadata-rich junction, the architecture supports complex organizational mappings. Constraints such as positive budget requirements and mandatory non-null foreign keys in assignments ensure data integrity across the system.