How jcidvidal/ferreteria-api works
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: service Services · controller API controllers · SecurityConfig.java Security · src React shell
Components 15
Spring Boot backend
API, business logic, persistence, and integration wiring.
- Boot app · Application bootstrap and overall composition root.
src/main/java/com/ferreteriapfeifer/ferreteria_api/FerreteriaApiApplication.java - Config · Initializes Firebase, Mercado Pago, and web behavior.
src/main/java/com/ferreteriapfeifer/ferreteria_api/config - Security · Spring Security setup, JWT filter, and access control rules.
src/main/java/com/ferreteriapfeifer/ferreteria_api/segurity/config/SecurityConfig.java - API controllers · REST ingress for auth, admin, customer, product, purchase, receipt, and payment flows.
src/main/java/com/ferreteriapfeifer/ferreteria_api/controller - Services · Coordinates validation, permissions, inventory, purchases, receipts, and payments.
src/main/java/com/ferreteriapfeifer/ferreteria_api/service - Repositories · Spring Data persistence boundary for core commerce entities.
src/main/java/com/ferreteriapfeifer/ferreteria_api/repository - Domain model · Commerce entities for users, products, purchases, payments, and receipts.
src/main/java/com/ferreteriapfeifer/ferreteria_api/model - DTOs · Wire formats for login, registration, payment preference, and webhook payloads.
src/main/java/com/ferreteriapfeifer/ferreteria_api/dto - JWT utils · Token creation/validation and password utilities.
src/main/java/com/ferreteriapfeifer/ferreteria_api/util - Mercado Pago · Payment preference creation and notification handling.
src/main/java/com/ferreteriapfeifer/ferreteria_api/service/MercadoPagoServiceImpl.java - Firebase · Firebase initialization and auxiliary client-side/cloud wiring.
src/main/java/com/ferreteriapfeifer/ferreteria_api/config/FirebaseInitializer.java - Receipt PDF · 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 · Bundled React application served from static assets.
src/main/resources/static/ferreteria-frontend/share/src - Customer UI · Product browsing, cart, and customer account experience.
src/main/resources/static/ferreteria-frontend/share/src/productos - Admin UI · Admin dashboards for customers, stock, sales, and complaints.
src/main/resources/static/ferreteria-frontend/share/src/funcionalidades
Connections 20
- 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.