Application Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
- Part1/API/src/main/java/com/example/api/ApiApplication.java
- Part1/API/src/main/resources/api-spec.yaml
- Part1/API/src/main/java/com/example/api/controller/EmployeeController.java
- Part1/API/src/main/java/com/example/api/service/EmployeeService.java
- Part1/API/src/main/java/com/example/api/security/SecurityConfig.java
- Part1/API/src/main/java/com/example/api/model/Employee.java
- Part1/API/src/main/java/com/example/api/model/Department.java
- Part1/API/src/main/java/com/example/api/model/Assignment.java
- Part1/API/src/main/java/com/example/api/exception/GlobalExceptionHandler.java
The SafeDispatch HQ Administration API is a Spring Boot-based RESTful service designed to manage corporate infrastructure, including employees, departments, and cross-departmental assignments. It provides a secure administrative interface for HR and Management staff to perform CRUD operations and execute specific business logic, such as employee promotions and departmental filtering.
The system follows a standard layered architecture, separating concerns between external API definitions, security enforcement, web controllers, business service logic, and data persistence via JPA.
Sources: Part1/API/src/main/resources/api-spec.yaml:1-6, Part1/API/src/main/java/com/example/api/ApiApplication.java:1-14
System Architecture
The application implements a multi-tiered architecture to ensure maintainability and security.
Layered Structure
- Presentation Layer: REST Controllers handle incoming HTTP requests, perform basic DTO mapping, and return standardized responses.
- Security Layer: Intercepts requests to enforce Role-Based Access Control (RBAC) and Basic Authentication.
- Service Layer: Contains the core business logic and cross-component orchestration (e.g., validating promotion eligibility).
- Data Access Layer: Repositories using Spring Data JPA interact with the underlying database.
The following diagram illustrates the flow of a typical request through the system:
The diagram shows the request-response lifecycle including the centralized exception handling mechanism.
Sources: Part1/API/src/main/java/com/example/api/security/SecurityConfig.java:44-59, Part1/API/src/main/java/com/example/api/exception/GlobalExceptionHandler.java:16-51
Domain Model and Data Schema
The core of the application revolves around three primary entities: Employee, Department, and Assignment. The Assignment entity serves as an associative entity to manage the many-to-many relationship between employees and departments, carrying additional metadata such as specific roles and access levels.
Entity Relationships
The ER diagram depicts the relationship where an Employee can have multiple Assignments across different Departments.
Sources: Part1/API/src/main/java/com/example/api/model/Employee.java:15-38, Part1/API/src/main/java/com/example/api/model/Department.java:13-26, Part1/API/src/main/java/com/example/api/model/Assignment.java:8-25
Security and Authentication
Security is implemented using Spring Security with HTTP Basic Authentication. Access control is strictly enforced based on user roles: HR and MANAGER.
Role-Based Access Control (RBAC)
| Method | Endpoint | Required Role |
|---|---|---|
| GET | /api/** | ROLE_HR or ROLE_MANAGER |
| POST | /api/** | ROLE_HR |
| PUT | /api/** | ROLE_HR |
| DELETE | /api/** | ROLE_HR |
Sources: Part1/API/src/main/java/com/example/api/security/SecurityConfig.java:48-53
Core Business Logic: Employee Promotion
One of the critical business processes implemented is the Promotion logic within the EmployeeService. This process enforces eligibility rules and applies automated changes to employee data.
Promotion Process Flow
- Eligibility Check: An employee must have a
startDaterecorded and have been with the company for at least 6 months. - Salary Increase: A 10% increase is applied to the current salary.
- Role Update: The employee's role string is prefixed with "Senior ".
API Endpoint Reference
The API is documented via OpenAPI and organized by resource tags.
| Tag | Endpoint | Operation | Description |
|---|---|---|---|
| Employees | GET /api/employees | getAllEmployees | List all employees, with optional department filter. |
| Employees | POST /api/employees | createEmployee | Register a new employee (HR Only). |
| Employees | PUT /api/employees/{id}/promote | promoteEmployee | Apply promotion logic to a specific employee. |
| Departments | POST /api/departments | createDepartment | Create a new department with a positive budget. |
| Assignments | POST /api/assignments | createAssignment | Link an employee to a department. |
Sources: Part1/API/src/main/resources/api-spec.yaml:94-290
Global Exception Handling
The application utilizes a @ControllerAdvice to ensure that errors are returned as structured JSON rather than raw stack traces.
Error Response Structure
{
"error": "Reason for the error"
}
The handler specifically catches ResponseStatusException, IllegalArgumentException (used for budget validation), and MethodArgumentNotValidException (used for @Email or @NotNull violations).
Sources: Part1/API/src/main/java/com/example/api/exception/GlobalExceptionHandler.java:16-43
Conclusion
The SafeDispatch HQ Administration API architecture provides a robust framework for organizational management. By leveraging Spring Boot's ecosystem, it ensures that security, business logic, and data persistence are handled in a structured, decoupled manner. The use of associative entities for assignments allows for complex organizational structures while maintaining strict role-based access for data integrity.