# jcidvidal/ferreteria-api architecture

> Architecture diagram of the GitHub repository jcidvidal/ferreteria-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jcidvidal/ferreteria-api
- Repository: https://github.com/jcidvidal/ferreteria-api

## Overview

1. **Overall shape**
   This repo is a **Spring Boot monolith** that exposes a REST API and also serves a bundled **React frontend** from `src/main/resources/static/ferreteria-frontend`. The architecture is centered on a classic layered backend with a separate client UI embedded into the same deployable application.

2. **Backend entry point and configuration**
   `FerreteriaApiApplication` is the Spring Boot bootstrap class. Startup wiring is handled by `config/*`, including `FirebaseInitializer`, `MercadoPagoInitializer`, and `WebConfig`. These classes establish external service setup and application-wide web behavior before the controllers start serving requests.

3. **Request handling layer**
   The API surface is split into controllers by business area: `AuthController`, `AdminController`, `ClienteController`, `ProductoController`, `CompraController`, `BoletaController`, and `MercadoPagoController`. These are the main ingress points for the frontend and any external callbacks, especially payment-related flows.

4. **Authentication and authorization boundary**
   Security is implemented with Spring Security plus a custom JWT filter in `jwtAuthFilter/JwtAuthFilter.java`. `segurity/config/SecurityConfig.java` defines protected endpoints and role-based access, while `util/JwtUtil` and `util/PasswordUtil` support token handling and password operations. This is the key boundary between anonymous users, customers, and admins.

5. **Business logic layer**
   The core orchestration lives in `service/*`: `AdminService`, `ClienteService`, `ProductoService`, `CompraService`, `BoletaService`, `GenerarPdfService`, and Mercado Pago services. These services coordinate validation, permission checks, inventory updates, purchase processing, receipt generation, and payment integration.

6. **Domain model**
   The domain is organized around ferretería commerce concepts in `model/*`: `Producto`, `Compra`, `DetalleProducto`, `Pago`, `Boleta`, `Cliente`, `Admin`, and shared abstractions like `Persona`. `GeneradorComprobante` suggests receipt/comprobante generation logic tied to sales workflows. These entities are the main objects moving through the service and repository layers.

7. **Persistence layer**
   Data access is abstracted through Spring Data repositories in `repository/*` for admins, clients, products, purchases, receipts, and payments. The repo structure indicates the services do not talk directly to storage; they go through repositories, keeping persistence isolated from the rest of the logic.

8. **Data transfer and API contracts**
   `dto/*` contains the request/response shapes used on the wire, including login, registration, payment notifications, preference creation, and token responses. This layer separates internal entities from external JSON contracts and is especially important for auth and Mercado Pago webhook handling.

9. **External integrations**
   The two significant integrations are **Firebase** and **Mercado Pago**. Firebase appears to be initialized on startup and is likely used by the frontend or auxiliary cloud features. Mercado Pago is wired through both a service layer and a controller, with DTOs for preferences and payment notifications, indicating a payment initiation flow plus asynchronous webhook confirmation flow.

10. **Frontend architecture**
   The React app is not a separate deployment unit here; it lives inside the backend’s static assets. There are multiple frontend entry points: `share/src/index.js`, `share/src/index-admin.js`, and app variants like `App_cliente.js`, `App_admin.js`, and `App_login_default.js`. This suggests the UI is split by role into customer and admin experiences.

11. **Frontend feature areas**
   The client UI is organized into functional sections such as product browsing and cart management (`productos/*`, `seguridad/*`), while the admin UI contains views for customers, stock, sales, complaints, and dashboards (`funcionalidades/*`, `css-admin/*`). Shared auth state and routing are handled through contexts and route guards like `AuthContext.js` and `PrivateRoute.js`.

12. **End-to-end data flow**
   A typical flow is: React UI sends requests to Spring controllers → controllers delegate to services → services validate and coordinate with repositories → persistence is updated and responses are mapped back through DTOs. For payments, the flow extends to Mercado Pago and then back through notification/webhook handling to finalize the purchase and issue boleta/comprobante data.

13. **Testing boundary**
   The test suite focuses on service-level correctness: `AdminServiceTest`, `BoletaServiceTest`, `CompraServiceTest`, `MercadoPagoServiceImplTest`, and `ProductoServiceTest`. This indicates the most important business rules are enforced and verified in the service layer rather than in controllers.

14. **Key architectural takeaway**
   The repo is best drawn as a **single Spring Boot backend with embedded role-based React frontend**, centered on commerce workflows: authentication, product/catalog management, purchase/payment processing, and digital receipt generation. The strongest boundaries are between UI, controller/API, service/business logic, repository/persistence, and external integrations.

Main entry points: [`src/main/java/com/ferreteriapfeifer/ferreteria_api/service`](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/service) (Services), [`src/main/java/com/ferreteriapfeifer/ferreteria_api/controller`](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/controller) (API controllers), [`src/main/java/com/ferreteriapfeifer/ferreteria_api/segurity/config/SecurityConfig.java`](https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/segurity/config/SecurityConfig.java) (Security), [`src/main/resources/static/ferreteria-frontend/share/src`](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/resources/static/ferreteria-frontend/share/src) (React shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Spring Boot backend"]
  node_app(("Boot app<br/>spring boot entrypoint"))
  node_config["Config"]
  node_security["Security"]
  node_controllers["API controllers<br/>rest layer"]
  node_services["Services<br/>business layer"]
  node_repositories["Repositories<br/>data access"]
  node_domain[("Domain model<br/>entities")]
  node_dtos["DTOs<br/>api contracts"]
  node_jwt["JWT utils<br/>token helpers"]
  node_mp["Mercado Pago<br/>payment integration"]
  node_firebase["Firebase<br/>cloud init"]
  node_pdf["Receipt PDF<br/>document service"]
end

subgraph group_frontend["Embedded React frontend"]
  node_frontend_shell["React shell<br/>embedded frontend"]
  node_customer_ui["Customer UI<br/>react client"]
  node_admin_ui["Admin UI<br/>react admin"]
end

node_app -->|"boots with"| node_config
node_app -->|"enables"| node_security
node_app -->|"hosts"| node_controllers
node_config -->|"initializes"| node_firebase
node_config -->|"initializes"| node_mp
node_security -->|"uses"| node_jwt
node_controllers -->|"delegates to"| node_services
node_controllers -->|"maps"| node_dtos
node_services -->|"persists via"| node_repositories
node_services -->|"orchestrates"| node_domain
node_services -->|"generates"| node_pdf
node_services -->|"integrates"| node_mp
node_mp -->|"accepts"| node_dtos
node_frontend_shell -->|"contains"| node_customer_ui
node_frontend_shell -->|"contains"| node_admin_ui
node_frontend_shell -->|"calls"| node_controllers
node_customer_ui -->|"authenticates via"| node_security
node_admin_ui -->|"authenticates via"| node_security
node_frontend_shell -->|"uses"| node_firebase
node_controllers -->|"protected by"| node_security

click node_app "https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/FerreteriaApiApplication.java"
click node_config "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/config"
click node_security "https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/segurity/config/SecurityConfig.java"
click node_controllers "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/controller"
click node_services "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/service"
click node_repositories "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/repository"
click node_domain "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/model"
click node_dtos "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/dto"
click node_jwt "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/util"
click node_mp "https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/service/MercadoPagoServiceImpl.java"
click node_firebase "https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/config/FirebaseInitializer.java"
click node_pdf "https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/service/GenerarPdfService.java"
click node_frontend_shell "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/resources/static/ferreteria-frontend/share/src"
click node_customer_ui "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/resources/static/ferreteria-frontend/share/src/productos"
click node_admin_ui "https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/resources/static/ferreteria-frontend/share/src/funcionalidades"

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_app,node_config,node_security,node_controllers,node_services,node_repositories,node_domain,node_dtos,node_jwt,node_mp,node_firebase,node_pdf toneBlue
class node_frontend_shell,node_customer_ui,node_admin_ui toneAmber
```

## Components

### Spring Boot backend

API, business logic, persistence, and integration wiring.

- [Boot app](https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/FerreteriaApiApplication.java): spring boot entrypoint · Application bootstrap and overall composition root. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/FerreteriaApiApplication.java`
- [Config](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/config): startup config · Initializes Firebase, Mercado Pago, and web behavior. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/config`
- [Security](https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/segurity/config/SecurityConfig.java): jwt security · Spring Security setup, JWT filter, and access control rules. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/segurity/config/SecurityConfig.java`
- [API controllers](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/controller): rest layer · REST ingress for auth, admin, customer, product, purchase, receipt, and payment flows. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/controller`
- [Services](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/service): business layer · Coordinates validation, permissions, inventory, purchases, receipts, and payments. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/service`
- [Repositories](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/repository): data access · Spring Data persistence boundary for core commerce entities. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/repository`
- [Domain model](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/model): entities · Commerce entities for users, products, purchases, payments, and receipts. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/model`
- [DTOs](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/dto): api contracts · Wire formats for login, registration, payment preference, and webhook payloads. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/dto`
- [JWT utils](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/util): token helpers · Token creation/validation and password utilities. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/util`
- [Mercado Pago](https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/service/MercadoPagoServiceImpl.java): payment integration · Payment preference creation and notification handling. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/service/MercadoPagoServiceImpl.java`
- [Firebase](https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/config/FirebaseInitializer.java): cloud init · Firebase initialization and auxiliary client-side/cloud wiring. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/config/FirebaseInitializer.java`
- [Receipt PDF](https://github.com/jcidvidal/ferreteria-api/blob/master/src/main/java/com/ferreteriapfeifer/ferreteria_api/service/GenerarPdfService.java): document service · Generates PDF receipts and comprobante artifacts. · `src/main/java/com/ferreteriapfeifer/ferreteria_api/service/GenerarPdfService.java`

### Embedded React frontend

Role-based UI bundled into backend static assets.

- [React shell](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/resources/static/ferreteria-frontend/share/src): embedded frontend · Bundled React application served from static assets. · `src/main/resources/static/ferreteria-frontend/share/src`
- [Customer UI](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/resources/static/ferreteria-frontend/share/src/productos): react client · Product browsing, cart, and customer account experience. · `src/main/resources/static/ferreteria-frontend/share/src/productos`
- [Admin UI](https://github.com/jcidvidal/ferreteria-api/tree/master/src/main/resources/static/ferreteria-frontend/share/src/funcionalidades): react admin · Admin dashboards for customers, stock, sales, and complaints. · `src/main/resources/static/ferreteria-frontend/share/src/funcionalidades`

## Connections

- Boot app → Config: boots with · Application startup loads infrastructure and web configuration.
- Boot app → Security: enables · Security filter chain and auth boundaries are part of startup wiring.
- Boot app → API controllers: hosts · Spring Boot exposes the REST API controllers.
- Config → Firebase: initializes · Firebase is configured during application startup.
- Config → Mercado Pago: initializes · Mercado Pago client setup happens at startup.
- Security → JWT utils: uses · Security depends on JWT/password utilities for auth decisions.
- API controllers → Services: delegates to · Controllers route requests into business services.
- API controllers → DTOs: maps · API endpoints consume and return DTOs.
- Services → Repositories: persists via · Business logic goes through repositories for storage access.
- Services → Domain model: orchestrates · Services operate on core domain entities.
- Services → Receipt PDF: generates · Sales/receipt workflows produce PDF documents.
- Services → Mercado Pago: integrates · Purchase flows interact with Mercado Pago.
- Mercado Pago → DTOs: accepts · Payment preference and webhook contracts are DTO-based.
- React shell → Customer UI: contains · Shared frontend bundle includes customer-facing screens.
- React shell → Admin UI: contains · Shared frontend bundle includes admin-facing screens.
- React shell → API controllers: calls · React screens consume the backend REST API.
- Customer UI → Security: authenticates via · Customer flows depend on JWT-backed login and access control.
- Admin UI → Security: authenticates via · Admin flows depend on protected routes and roles.
- React shell → Firebase: uses · Frontend includes Firebase client configuration for auxiliary features.
- API controllers → Security: protected by · API endpoints are guarded by the security boundary.
