e2-systems/construplan

1. Overall shape

ConstruPlan is a single Spring Boot 3.x monolith with server-rendered UI. Requests come from browsers, are handled by Spring MVC controllers, pass through Spring Security, then flow into service and repository layers backed by JPA/MySQL.

2. Presentation layer

The UI is built with Thymeleaf templates under src/main/resources/templates. Views are grouped by business area: admin, auth, campo, empleado, oficina, tickets, plus shared fragments and error pages. This indicates a classic MVC app rather than a SPA or API-first system.

3. Security and entry flow

Authentication is centralized in config/SecurityConfig and the auth controllers under auth/. Login uses the database-backed user table via Spring Security, and the app redirects users to role-specific dashboards: ADMIN, OFICINA, CAMPO, and EMPLEADO. Security is a cross-cutting boundary around all feature modules.

4. Domain modularization

The backend is organized by business capability, not by technical layer alone:

- admin: system administration, projects, users, configuration

- campo: field operations, tasks, goals, assignments, production validation

- empleado: employee self-service, attendance, tickets

- oficina: payroll, adjustments, reports, salary management

- shared model, repository, service, config, exception, util

This structure is important for diagramming because each module has its own controllers, entities, repositories, and services.

5. Core data model

The shared identity model centers on Usuario and Rol. The employee domain adds Empleado, RegistroDiario, and Ticket. The field domain centers on Tarea, Meta, and AsignacionTarea. The office/payroll domain centers on Planilla, PlanillaDetalle, Sueldo, and AjustePlanilla. These are separate bounded contexts connected by shared references, not one flat model.

6. Important cross-entity relationships

The most important business flow is AsignacionTarea: it links an Empleado, the assigning Usuario, a Proyecto, and a Meta. Another key relationship is Usuario to Empleado, which is optional in one direction but required for employees who access the system. Meta belongs to Tarea, translating a generic task into measurable work targets.

7. Service and repository boundaries

Each feature module has a service layer that contains transactional business rules and a repository layer that performs persistence. Examples include UsuarioService, ProyectoService, MetaService, PlanillaService, and TicketService. Repositories are Spring Data JPA interfaces, so the application’s data access boundary is database-centric rather than service-to-service.

8. Field operations flow

The campo module appears to handle the operational side of construction work: assigning tasks, defining goals, validating production, and measuring progress. It also includes DTOs like EmpleadoRendimientoDTO and ProyectoAvanceDTO, which suggests aggregate views for dashboards rather than direct entity exposure.

9. Payroll and reporting flow

The oficina module is the payroll engine. It manages payroll periods, payroll details, salary definitions, and adjustments, and it also generates reports. JasperReports is integrated through config/JasperConfig, with a .jrxml report template for weekly payroll. This is the main reporting/output boundary in the system.

10. Employee self-service

The empleado module provides the employee-facing dashboard and workflows for attendance, profile, and ticketing. It is a separate front-door from office/admin use, even though it shares the same authentication and persistence infrastructure.

11. Shared infrastructure and error handling

Cross-cutting configuration lives in config/: JPA setup, security, and Jasper reporting. Error handling is centralized in GlobalExceptionHandler with a custom ResourceNotFoundException, and there are dedicated error templates for 403/404/500. This keeps exception behavior consistent across all modules.

12. Runtime and deployment assumptions

The app expects MySQL on port 3306 with schema construplan, and JPA validation is configured instead of schema auto-creation. That means the database schema is an external prerequisite, not something the app freely mutates at startup. The project is built with Maven and has a GitHub Actions workflow for automated build/test execution.

13. Diagramming takeaway

If you draw the architecture, the main picture should be: Browser → Thymeleaf MVC controllers → service layer → JPA repositories → MySQL, wrapped by Spring Security and supported by JasperReports for document output. The real architectural boundary is the business module: admin, field, employee, and office each own their own screens, services, and data models while sharing authentication and infrastructure.