# e2-systems/construplan architecture

> Architecture diagram of the GitHub repository e2-systems/construplan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/e2-systems/construplan
- Repository: https://github.com/e2-systems/construplan

## Overview

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.

Main entry points: [`src/main/java/com/construplan/admin/repository/UsuarioRepository.java`](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/repository/UsuarioRepository.java) (Repositories), [`src/main/resources/templates/admin/dashboard.html`](https://github.com/e2-systems/construplan/blob/main/src/main/resources/templates/admin/dashboard.html) (Thymeleaf views), [`src/main/java/com/construplan/ConstruplanApplication.java`](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/ConstruplanApplication.java) (ConstruPlan), [`src/main/java/com/construplan/oficina/service/PlanillaService.java`](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/oficina/service/PlanillaService.java) (Office services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_authctl["Auth UI<br/>Auth controllers"]
  node_adminui["Admin UI<br/>Admin controllers"]
  node_campoui["Campo UI<br/>Field controllers"]
  node_empleadoui["Empleado UI<br/>Employee controllers"]
  node_oficinaui["Oficina UI<br/>Office controllers"]
  node_templates["Thymeleaf views<br/>MVC templates<br/>[dashboard.html]"]
end

subgraph group_domain["Business domains"]
  node_adminsvc["Admin services<br/>User/project service layer"]
  node_project["Project model<br/>Project aggregate<br/>[Proyecto.java]"]
  node_authdomain["Auth service<br/>Login service<br/>[AuthService.java]"]
  node_campo["Campo services<br/>Field operations"]
  node_fieldmodel["Field model<br/>Tasking entities"]
  node_empleadosvc["Employee services<br/>Self-service"]
  node_empleadomodel["Employee model<br/>HR entities<br/>[Empleado.java]"]
  node_oficinasvc["Office services<br/>Payroll service"]
  node_payrollmodel["Payroll model<br/>Payroll entities<br/>[Planilla.java]"]
end

subgraph group_infrastructure["Infrastructure"]
  node_app(("ConstruPlan<br/>Spring Boot app"))
  node_security["Security"]
  node_jpa["JPA config<br/>Persistence config<br/>[JpaConfig.java]"]
  node_jasper["Reports<br/>Jasper config<br/>[JasperConfig.java]"]
  node_errors["Errors<br/>Exception handler"]
  node_repos[("Repositories")]
  node_reports["JRXML report<br/>Payroll template"]
  node_mysql[("MySQL<br/>External DB")]
end

node_app -->|"boots with"| node_security
node_app -->|"uses"| node_jpa
node_app -->|"uses"| node_jasper
node_app -->|"handles"| node_errors
node_security -->|"protects"| node_authctl
node_security -->|"auth via"| node_repos
node_authctl -->|"renders"| node_templates
node_adminui -->|"renders"| node_templates
node_campoui -->|"renders"| node_templates
node_empleadoui -->|"renders"| node_templates
node_oficinaui -->|"renders"| node_templates
node_adminui -->|"calls"| node_adminsvc
node_adminsvc -->|"manages"| node_project
node_authdomain -->|"reads"| node_repos
node_campo -->|"orchestrates"| node_fieldmodel
node_campo -->|"persists"| node_repos
node_empleadosvc -->|"orchestrates"| node_empleadomodel
node_empleadosvc -->|"persists"| node_repos
node_oficinasvc -->|"orchestrates"| node_payrollmodel
node_oficinasvc -->|"generates"| node_reports
node_oficinasvc -->|"persists"| node_repos
node_repos -->|"stores"| node_mysql
node_errors -->|"serves"| node_templates

click node_app "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/ConstruplanApplication.java"
click node_security "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/config/SecurityConfig.java"
click node_jpa "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/config/JpaConfig.java"
click node_jasper "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/config/JasperConfig.java"
click node_errors "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/exception/GlobalExceptionHandler.java"
click node_authctl "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/auth/controller/AuthController.java"
click node_adminui "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/controller/AdminController.java"
click node_campoui "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/campo/controller/CampoController.java"
click node_empleadoui "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/empleado/controller/EmpleadoController.java"
click node_oficinaui "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/oficina/controller/OficinaController.java"
click node_adminsvc "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/service/UsuarioService.java"
click node_project "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/model/entity/Proyecto.java"
click node_authdomain "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/auth/service/AuthService.java"
click node_campo "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/campo/service/AsignacionTareaService.java"
click node_fieldmodel "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/campo/model/entity/AsignacionTarea.java"
click node_empleadosvc "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/empleado/service/EmpleadoService.java"
click node_empleadomodel "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/empleado/model/entity/Empleado.java"
click node_oficinasvc "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/oficina/service/PlanillaService.java"
click node_payrollmodel "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/oficina/model/entity/Planilla.java"
click node_repos "https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/repository/UsuarioRepository.java"
click node_templates "https://github.com/e2-systems/construplan/blob/main/src/main/resources/templates/admin/dashboard.html"
click node_reports "https://github.com/e2-systems/construplan/blob/main/src/main/resources/reports/weekly_payroll.jrxml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_authctl,node_adminui,node_campoui,node_empleadoui,node_oficinaui,node_templates toneBlue
class node_adminsvc,node_project,node_authdomain,node_campo,node_fieldmodel,node_empleadosvc,node_empleadomodel,node_oficinasvc,node_payrollmodel toneAmber
class node_app,node_security,node_jpa,node_jasper,node_errors,node_repos,node_reports,node_mysql toneMint
```

## Components

### Presentation

Server-rendered MVC UI and entry controllers

- [Auth UI](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/auth/controller/AuthController.java): Auth controllers · Login and authentication entry points · `src/main/java/com/construplan/auth/controller/AuthController.java`
- [Admin UI](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/controller/AdminController.java): Admin controllers · Administration screens for projects, users, and configuration · `src/main/java/com/construplan/admin/controller/AdminController.java`
- [Campo UI](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/campo/controller/CampoController.java): Field controllers · Field operations screens for tasks, goals, and validation · `src/main/java/com/construplan/campo/controller/CampoController.java`
- [Empleado UI](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/empleado/controller/EmpleadoController.java): Employee controllers · Employee self-service screens and workflows · `src/main/java/com/construplan/empleado/controller/EmpleadoController.java`
- [Oficina UI](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/oficina/controller/OficinaController.java): Office controllers · Payroll, reports, and office operations screens · `src/main/java/com/construplan/oficina/controller/OficinaController.java`
- [Thymeleaf views](https://github.com/e2-systems/construplan/blob/main/src/main/resources/templates/admin/dashboard.html): MVC templates · Server-rendered pages and shared fragments · `src/main/resources/templates/admin/dashboard.html`

### Business domains

Capability-based feature modules

- [Admin services](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/service/UsuarioService.java): User/project service layer · Administration business rules and user/project management · `src/main/java/com/construplan/admin/service/UsuarioService.java`
- [Project model](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/model/entity/Proyecto.java): Project aggregate · Projects and system configuration data · `src/main/java/com/construplan/admin/model/entity/Proyecto.java`
- [Auth service](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/auth/service/AuthService.java): Login service · Authentication flow backed by database users · `src/main/java/com/construplan/auth/service/AuthService.java`
- [Campo services](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/campo/service/AsignacionTareaService.java): Field operations · Task assignment, goals, and production validation logic · `src/main/java/com/construplan/campo/service/AsignacionTareaService.java`
- [Field model](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/campo/model/entity/AsignacionTarea.java): Tasking entities · Tasks, goals, assignments, and progress views · `src/main/java/com/construplan/campo/model/entity/AsignacionTarea.java`
- [Employee services](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/empleado/service/EmpleadoService.java): Self-service · Attendance, employee profile, and ticket workflows · `src/main/java/com/construplan/empleado/service/EmpleadoService.java`
- [Employee model](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/empleado/model/entity/Empleado.java): HR entities · Employee, attendance, and ticket data · `src/main/java/com/construplan/empleado/model/entity/Empleado.java`
- [Office services](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/oficina/service/PlanillaService.java): Payroll service · Payroll calculations, salary management, and reporting · `src/main/java/com/construplan/oficina/service/PlanillaService.java`
- [Payroll model](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/oficina/model/entity/Planilla.java): Payroll entities · Payroll periods, details, salaries, and adjustments · `src/main/java/com/construplan/oficina/model/entity/Planilla.java`

### Infrastructure

Security, persistence, reporting, and error handling

- [ConstruPlan](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/ConstruplanApplication.java): Spring Boot app · Application entrypoint and runtime container · `src/main/java/com/construplan/ConstruplanApplication.java`
- [Security](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/config/SecurityConfig.java): Spring Security config · Central authentication and authorization boundary · `src/main/java/com/construplan/config/SecurityConfig.java`
- [JPA config](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/config/JpaConfig.java): Persistence config · JPA and database integration setup · `src/main/java/com/construplan/config/JpaConfig.java`
- [Reports](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/config/JasperConfig.java): Jasper config · Reporting and document generation setup · `src/main/java/com/construplan/config/JasperConfig.java`
- [Errors](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/exception/GlobalExceptionHandler.java): Exception handler · Global MVC error handling and not-found mapping · `src/main/java/com/construplan/exception/GlobalExceptionHandler.java`
- [Repositories](https://github.com/e2-systems/construplan/blob/main/src/main/java/com/construplan/admin/repository/UsuarioRepository.java): JPA repositories · Spring Data persistence boundary across modules · `src/main/java/com/construplan/admin/repository/UsuarioRepository.java`
- [JRXML report](https://github.com/e2-systems/construplan/blob/main/src/main/resources/reports/weekly_payroll.jrxml): Payroll template · Weekly payroll report template · `src/main/resources/reports/weekly_payroll.jrxml`
- **MySQL**: External DB · Database backing users, domain entities, and payroll data

## Connections

- ConstruPlan → Security: boots with · Application starts under security configuration
- ConstruPlan → JPA config: uses · Loads persistence configuration
- ConstruPlan → Reports: uses · Loads reporting configuration
- ConstruPlan → Errors: handles · Centralized MVC exception handling
- Security → Auth UI: protects · Security boundary around login and app routes
- Security → Repositories: auth via · Loads users and roles from persistence
- Auth UI → Thymeleaf views: renders · Login and auth views
- Admin UI → Thymeleaf views: renders · Admin pages and shared fragments
- Campo UI → Thymeleaf views: renders · Campo dashboards and forms
- Empleado UI → Thymeleaf views: renders · Employee pages and dashboards
- Oficina UI → Thymeleaf views: renders · Office and payroll pages
- Admin UI → Admin services: calls · Admin actions delegate to services
- Admin services → Project model: manages · Projects and configuration data
- Auth service → Repositories: reads · Authenticates against user data
- Campo services → Field model: orchestrates · Assigns tasks and tracks progress
- Campo services → Repositories: persists · Field domain persistence
- Employee services → Employee model: orchestrates · Attendance and ticket workflows
- Employee services → Repositories: persists · Employee domain persistence
- Office services → Payroll model: orchestrates · Payroll and adjustment processing
- Office services → JRXML report: generates · Produces weekly payroll reports
- Office services → Repositories: persists · Payroll domain persistence
- Repositories → MySQL: stores · JPA-backed database access
- Errors → Thymeleaf views: serves · 403, 404, and 500 error pages