Department Management Feature

Relevant source files

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

• Part1/API/src/main/java/com/example/api/model/Department.java
• Part1/API/src/main/java/com/example/api/service/DepartmentService.java
• Part1/API/src/main/java/com/example/api/controller/DepartmentController.java
• Part1/API/src/main/java/com/example/api/repository/DepartmentRepository.java
• Part1/API/src/main/resources/api-spec.yaml
• Part1/API/src/main/java/com/example/api/security/SecurityConfig.java
• Part1/API/src/test/java/com/example/api/DepartmentServiceTest.java

The Department Management Feature is a core component of the SafeDispatch HQ Administration API, designed to allow administrators to organize the workforce into distinct logical units. This system handles the lifecycle of departments, including their creation, budget allocation, and geographical tracking. It serves as a structural foundation for the Assignment System and employee organization.

The feature is built using a standard Spring Boot tiered architecture (Controller-Service-Repository) and enforces strict business rules regarding financial constraints. Access is strictly controlled through role-based security, ensuring that only authorized personnel can modify organizational structures.

Sources: Part1/API/src/main/resources/api-spec.yaml:4-8, Part1/API/src/main/java/com/example/api/model/Department.java:10-25

Architecture and Data Flow

The Department Management system follows a synchronous request-response pattern. Data flows from the REST controller through a service layer that implements business validation before persisting data via Spring Data JPA.

Data Validation Logic

A critical business rule enforced in the service layer and model is the budget constraint. Every department must have a positive integer budget. This is validated using both Jakarta Validation annotations and manual checks within the service layer.

The flow above illustrates how a department creation request is processed and validated.
Sources: Part1/API/src/main/java/com/example/api/service/DepartmentService.java:24-29, Part1/API/src/main/java/com/example/api/model/Department.java:18-19

Data Model

The Department entity is the primary data structure, representing a physical or logical branch of the company.

Field	Type	Constraints	Description
id	Long	Primary Key, Auto-gen	Unique identifier for the department.
name	String	Required	The name of the department (e.g., Logistics).
budget	Integer	@Positive, Required	Annual budget allocated to the department.
location	String	Required	Physical location (e.g., Leicester).
assignments	List	One-to-Many	Collection of employee-department links.

Sources: Part1/API/src/main/java/com/example/api/model/Department.java:11-26, Part1/API/src/main/resources/api-spec.yaml:70-87

Assignment Data Relationships

Departments are linked to employees via an Assignment entity. This allows for a many-to-many relationship effectively handled as two one-to-many relationships.

The ER diagram shows how departments aggregate assignments to track their workforce.
Sources: Part1/API/src/main/java/com/example/api/model/Department.java:24-25, Part1/API/src/main/java/com/example/api/model/Assignment.java:11-20

API Endpoints

The system exposes RESTful endpoints for department administration.

Method	Endpoint	Description	Security Requirement
GET	/api/departments	Lists all departments.	ROLE_MANAGER or ROLE_HR
POST	/api/departments	Creates a new department.	ROLE_HR only
GET	/api/departments/{id}/employees	Lists all employees in a specific department.	ROLE_MANAGER or ROLE_HR

Department Creation Sequence

The following sequence diagram outlines the creation of a department, including the security and service-level validation steps.

Implementation Details

Repository Queries

The DepartmentRepository extends JpaRepository and includes a custom JPQL query to bridge the gap between departments and employees through the assignment table.

// Part1/API/src/main/java/com/example/api/repository/DepartmentRepository.java:16-18
@Query("SELECT a.employee FROM Assignment a WHERE a.department.id = :deptId")
List<Employee> findEmployeesByDepartmentId(@Param("deptId") Long deptId);

Sources: Part1/API/src/main/java/com/example/api/repository/DepartmentRepository.java:13-19

Business Validation

The service layer ensures data integrity. If a budget is null or non-positive, an IllegalArgumentException is thrown, which is subsequently handled by the GlobalExceptionHandler to return a clean JSON error response.

// Part1/API/src/main/java/com/example/api/service/DepartmentService.java:24-29
public Department createDepartment(Department department) {
    if (department.getBudget() == null || department.getBudget() <= 0) {
        throw new IllegalArgumentException("Budget must be positive");
    }
    return departmentRepository.save(department);
}

Sources: Part1/API/src/main/java/com/example/api/service/DepartmentService.java:24-29, Part1/API/src/test/java/com/example/api/DepartmentServiceTest.java:29-38

Summary

The Department Management Feature provides a robust framework for managing the organizational structure of SafeDispatch. By integrating role-based access control, strict financial validation, and a relational mapping between departments and staff, it ensures that company resources are organized securely and logically. Significant emphasis is placed on budget integrity and the clear separation of administrative concerns.