# it0xhl/prueba-mantenimiento-de-clientes architecture

> Architecture diagram of the GitHub repository it0xhl/prueba-mantenimiento-de-clientes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/it0xhl/prueba-mantenimiento-de-clientes
- Repository: https://github.com/it0xhl/prueba-mantenimiento-de-clientes

## Overview

1. **Repository shape**
   - This is a three-part system: **Angular frontend**, **Spring Boot backend**, and **SQL Server database assets**.
   - The repo is organized so each layer can run independently, but the intended path is frontend → REST API → SQL Server.

2. **Frontend boundary**
   - The `frontend/` app is an Angular 21 SPA built around a single business feature: **client maintenance**.
   - Main UI pieces are split into:
     - `pages/cliente-page`: the screen/container for the feature
     - `components/cliente-form`: create/update form
     - `components/cliente-table`: list, pagination, and row selection
   - `main.ts` and `app.config.ts` indicate a modern Angular bootstrap setup rather than a classic NgModule-heavy app.

3. **Frontend state and data flow**
   - `core/cliente.store.ts` is the key client-side state boundary: it likely coordinates list loading, selection, and mutation results.
   - `services/cliente.service.ts` is the API adapter that talks to the backend.
   - `models/cliente.model.ts` defines the client shape used in the UI; `format.util.ts` suggests presentation helpers for dates/text.
   - Typical flow is: user edits form → store/service sends request → table refreshes from API → UI shows success/error feedback.

4. **Frontend validation and UX**
   - Validation is enforced before submission using Angular reactive forms, matching backend rules.
   - The UI supports:
     - live search
     - pagination with page-size choices
     - row selection for edit
     - confirm-before-delete behavior
   - Because validation exists in both tiers, the frontend is not trusted as the only guardrail.

5. **Backend structure**
   - The backend is a Spring Boot 3.5 API under `com.prueba.clientes`.
   - Layers are cleanly separated:
     - `controller/ClienteController.java` for HTTP endpoints
     - `service/ClienteService` + `service/impl/ClienteServiceImpl` for business logic
     - `repository/` for persistence access
     - `domain/Cliente.java` as the JPA entity
     - `dto/` for request/response contracts
     - `exception/` for centralized error handling

6. **Backend API contract**
   - The API base is `/api/v1/clientes`.
   - Responses are wrapped in a consistent envelope via `ApiResponse` and `PageResponse`, so the UI always receives structured success/message/data payloads.
   - The backend exposes the full CRUD set plus paginated search:
     - list with search/paging
     - get by id
     - create
     - update
     - delete

7. **Backend persistence model**
   - `Cliente` maps to the SQL Server table `dbo.Cliente`.
   - The persistence strategy is intentionally mixed:
     - **Spring Data JPA** for read/create/update flows
     - **stored procedure** for delete
   - `ClienteRepositoryCustom` and `ClienteRepositoryCustomImpl` are the boundary for custom database behavior, most likely including the delete procedure and possibly search logic.

8. **Database subsystem**
   - The `database/` folder is a first-class part of the architecture, not just seed data.
   - It contains scripts to:
     - create the database
     - create tables
     - create stored procedures
     - seed initial data
   - The key operational dependency is SQL Server 2022, and the system expects a preloaded schema plus procedure `dbo.usp_EliminarCliente`.

9. **Cross-cutting concerns**
   - `WebCorsConfig` defines the frontend-to-backend trust boundary for browser calls.
   - `OpenApiConfig` documents the API, surfacing Swagger/OpenAPI for interactive exploration.
   - `GlobalExceptionHandler` and `ResourceNotFoundException` centralize error translation so the API returns controlled responses rather than raw stack traces.
   - Validation is mirrored in both frontend and backend using Jakarta Validation on the server side.

10. **Runtime and deployment topology**
   - Local runtime is explicitly container-assisted:
     - `docker-compose.yml` brings up SQL Server on exposed port `14336`
     - backend runs on `8081`
     - frontend runs on `4200`
   - Environment variables drive DB and CORS configuration, so the backend is configurable without code changes.
   - `start.bat` acts as an orchestration entrypoint on Windows: it checks Docker, starts the DB, initializes scripts, and opens backend + frontend sessions.

11. **Test boundaries**
   - Backend tests are split by layer:
     - `ClienteControllerTest`
     - `ClienteServiceImplTest`
   - This suggests the architecture is validated at both HTTP and service boundaries, not just unit-level entity tests.

12. **Architecture diagram takeaway**
   - The main draw should be: **Angular SPA** on the left, **Spring Boot REST API** in the middle, and **SQL Server with schema + stored procedure scripts** on the right.
   - The most important internal arrows are:
     - UI form/table → Angular store/service → REST controller
     - controller → service → repository/JPA
     - delete path → custom repository → stored procedure
     - shared error/validation/doc config wrapping the API on the backend side.

Main entry points: [`backend/src/main/java/com/prueba/clientes/controller/ClienteController.java`](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/controller/ClienteController.java) (Cliente API), [`backend/src/main/java/com/prueba/clientes/repository/ClienteRepository.java`](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/repository/ClienteRepository.java) (Cliente repo), [`frontend/src/app/core/cliente.store.ts`](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/core/cliente.store.ts) (Client store), [`docker-compose.yml`](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/docker-compose.yml) (Runtime bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Angular SPA"]
  node_frontend_app["Angular app<br/>SPA shell<br/>[app.ts]"]
  node_cliente_page["Cliente page<br/>feature container<br/>[cliente-page.ts]"]
  node_cliente_form["Cliente form<br/>reactive form<br/>[cliente-form.ts]"]
  node_cliente_table["Cliente table<br/>list/grid<br/>[cliente-table.ts]"]
  node_cliente_store["Client store<br/>state boundary<br/>[cliente.store.ts]"]
  node_cliente_service_fe["API service<br/>HTTP adapter<br/>[cliente.service.ts]"]
  node_cliente_model["Client model<br/>UI model<br/>[cliente.model.ts]"]
end

subgraph group_backend["Spring API"]
  node_backend_api["Cliente API<br/>REST controller"]
  node_backend_service["Cliente service<br/>business service"]
  node_backend_repo["Cliente repo<br/>persistence repo"]
  node_backend_domain["Cliente entity<br/>JPA entity<br/>[Cliente.java]"]
  node_backend_dto["API DTOs<br/>contracts"]
  node_backend_errors["Error handling<br/>cross-cutting"]
  node_backend_config["API config<br/>cross-cutting<br/>[WebCorsConfig.java]"]
end

subgraph group_database["SQL Server Assets"]
  node_db_schema["Schema scripts<br/>SQL DDL"]
  node_db_proc["Stored proc<br/>SQL procedure"]
  node_db_seed["Seed data<br/>SQL seed<br/>[04_seed_data.sql]"]
end

node_runtime_boot["Runtime bootstrap<br/>orchestration<br/>[docker-compose.yml]"]

node_frontend_app -->|"hosts"| node_cliente_page
node_cliente_page -->|"uses"| node_cliente_form
node_cliente_page -->|"uses"| node_cliente_table
node_cliente_form -->|"submit"| node_cliente_store
node_cliente_table -->|"selection/search"| node_cliente_store
node_cliente_store -->|"API calls"| node_cliente_service_fe
node_cliente_service_fe -->|"REST"| node_backend_api
node_cliente_store -->|"reads/writes"| node_cliente_model
node_backend_api -->|"contracts"| node_backend_dto
node_backend_api -->|"delegates"| node_backend_service
node_backend_service -->|"persists"| node_backend_repo
node_backend_service -->|"maps"| node_backend_domain
node_backend_repo -->|"orm"| node_backend_domain
node_backend_repo -->|"reads/writes"| node_db_schema
node_backend_repo -->|"delete path"| node_db_proc
node_backend_api -->|"handled by"| node_backend_errors
node_backend_api -->|"configured by"| node_backend_config
node_db_schema -->|"initialized by"| node_db_seed
node_runtime_boot -.->|"starts"| node_db_schema
node_runtime_boot -.->|"starts"| node_backend_api
node_runtime_boot -.->|"starts"| node_frontend_app
node_cliente_service_fe -.->|"cors-sensitive"| node_backend_config
node_backend_api -->|"returns"| node_backend_dto

click node_frontend_app "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/app.ts"
click node_cliente_page "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/pages/cliente-page/cliente-page.ts"
click node_cliente_form "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/components/cliente-form/cliente-form.ts"
click node_cliente_table "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/components/cliente-table/cliente-table.ts"
click node_cliente_store "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/core/cliente.store.ts"
click node_cliente_service_fe "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/services/cliente.service.ts"
click node_cliente_model "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/models/cliente.model.ts"
click node_backend_api "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/controller/ClienteController.java"
click node_backend_service "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/service/impl/ClienteServiceImpl.java"
click node_backend_repo "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/repository/ClienteRepository.java"
click node_backend_domain "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/domain/Cliente.java"
click node_backend_dto "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/dto/ClienteRequest.java"
click node_backend_errors "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/exception/GlobalExceptionHandler.java"
click node_backend_config "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/config/WebCorsConfig.java"
click node_db_schema "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/database/02_create_tables.sql"
click node_db_proc "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/database/03_stored_procedures.sql"
click node_db_seed "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/database/04_seed_data.sql"
click node_runtime_boot "https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/docker-compose.yml"

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_frontend_app,node_cliente_page,node_cliente_form,node_cliente_table,node_cliente_store,node_cliente_service_fe,node_cliente_model toneBlue
class node_backend_api,node_backend_service,node_backend_repo,node_backend_domain,node_backend_dto,node_backend_errors,node_backend_config toneAmber
class node_db_schema,node_db_proc,node_db_seed toneMint
class node_runtime_boot toneNeutral
```

## Components

### Angular SPA

Client-side application for customer maintenance

- [Angular app](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/app.ts): SPA shell · Angular 21 bootstrap and application composition · `frontend/src/app/app.ts`
- [Cliente page](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/pages/cliente-page/cliente-page.ts): feature container · Top-level screen for client maintenance · `frontend/src/app/pages/cliente-page/cliente-page.ts`
- [Cliente form](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/components/cliente-form/cliente-form.ts): reactive form · Create and update form with validation and submit actions · `frontend/src/app/components/cliente-form/cliente-form.ts`
- [Cliente table](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/components/cliente-table/cliente-table.ts): list/grid · Search, pagination, row selection, and delete/edit entry points · `frontend/src/app/components/cliente-table/cliente-table.ts`
- [Client store](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/core/cliente.store.ts): state boundary · Coordinates loading, selection, mutations, and refresh flows · `frontend/src/app/core/cliente.store.ts`
- [API service](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/services/cliente.service.ts): HTTP adapter · Front-end adapter to the REST API · `frontend/src/app/services/cliente.service.ts`
- [Client model](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/frontend/src/app/models/cliente.model.ts): UI model · Shared client shape used by the Angular feature · `frontend/src/app/models/cliente.model.ts`

### Spring API

REST backend with service, persistence, and cross-cutting layers

- [Cliente API](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/controller/ClienteController.java): REST controller · HTTP boundary for /api/v1/clientes · `backend/src/main/java/com/prueba/clientes/controller/ClienteController.java`
- [Cliente service](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/service/impl/ClienteServiceImpl.java): business service · Service interface and implementation for CRUD and search logic · `backend/src/main/java/com/prueba/clientes/service/impl/ClienteServiceImpl.java`
- [Cliente repo](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/repository/ClienteRepository.java): persistence repo · Spring Data repository and custom persistence boundary · `backend/src/main/java/com/prueba/clientes/repository/ClienteRepository.java`
- [Cliente entity](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/domain/Cliente.java): JPA entity · Maps client records to dbo.Cliente · `backend/src/main/java/com/prueba/clientes/domain/Cliente.java`
- [API DTOs](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/dto/ClienteRequest.java): contracts · Request, response, page, and envelope models · `backend/src/main/java/com/prueba/clientes/dto/ClienteRequest.java`
- [Error handling](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/exception/GlobalExceptionHandler.java): cross-cutting · Global exception mapping and not-found translation · `backend/src/main/java/com/prueba/clientes/exception/GlobalExceptionHandler.java`
- [API config](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/backend/src/main/java/com/prueba/clientes/config/WebCorsConfig.java): cross-cutting · CORS and OpenAPI configuration for browser access and docs · `backend/src/main/java/com/prueba/clientes/config/WebCorsConfig.java`

### SQL Server Assets

Database schema, procedures, and seed scripts

- [Schema scripts](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/database/02_create_tables.sql): SQL DDL · Database and table creation scripts · `database/02_create_tables.sql`
- [Stored proc](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/database/03_stored_procedures.sql): SQL procedure · Delete procedure boundary used by the backend · `database/03_stored_procedures.sql`
- [Seed data](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/database/04_seed_data.sql): SQL seed · Initial data load scripts · `database/04_seed_data.sql`

### Other components

- [Runtime bootstrap](https://github.com/it0xhl/prueba-mantenimiento-de-clientes/blob/main/docker-compose.yml): orchestration · Docker Compose and Windows start script for local environment · `docker-compose.yml`

## Connections

- Angular app → Cliente page: hosts · Application renders the maintenance screen
- Cliente page → Cliente form: uses · Page composes the edit/create form
- Cliente page → Cliente table: uses · Page composes the searchable table
- Cliente form → Client store: submit · Form actions flow through shared state
- Cliente table → Client store: selection/search · Table drives paging, selection, and refresh
- Client store → API service: API calls · Store delegates persistence operations to HTTP adapter
- API service → Cliente API: REST · Frontend calls the client API endpoints
- Client store → Client model: reads/writes · State is shaped by the shared client model
- Cliente API → API DTOs: contracts · Controller exchanges request/response envelopes
- Cliente API → Cliente service: delegates · HTTP layer forwards operations to the service layer
- Cliente service → Cliente repo: persists · Service uses repository abstraction for data access
- Cliente service → Cliente entity: maps · Business logic works over the JPA entity model
- Cliente repo → Cliente entity: orm · Repository persists Cliente entities
- Cliente repo → Schema scripts: reads/writes · Entity table defined in schema scripts
- Cliente repo → Stored proc: delete path · Custom repository invokes stored procedure for delete
- Cliente API → Error handling: handled by · Controller exceptions are normalized centrally
- Cliente API → API config: configured by · CORS and OpenAPI shape the API boundary
- Schema scripts → Seed data: initialized by · Seed scripts populate the created schema
- Runtime bootstrap → Schema scripts: starts · Local orchestration initializes database assets
- Runtime bootstrap → Cliente API: starts · Orchestration brings up backend runtime
- Runtime bootstrap → Angular app: starts · Orchestration brings up frontend runtime
- API service → API config: cors-sensitive · Browser calls rely on server CORS configuration
- Cliente API → API DTOs: returns · Structured ApiResponse and PageResponse envelopes
