How josealbertonp/api-pessoa works
Project type and purpose
• This is a monolithic, backend-only REST API built with Spring Boot (Java 17) that exposes CRUD operations on a Pessoa (Person) entity.
• It uses MySQL for persistence, is containerized via Docker/Docker Compose, and provides Swagger UI for interactive documentation.
File structure
• src/main/java/com/pessoa/apipessoa
• ApiPessoaApplication.java (entry point)
• controller/ (REST controllers)
• service/ (business logic)
• repository/ (Spring Data JPA interfaces)
• entity/ (JPA entities)
• DTOs/request + DTOs/response (data transfer objects)
• config/ (WebConfig, SwaggerConfig)
• exception/ (custom exceptions and global handler)
• src/main/resources/application.properties (DB and app settings)
• init/init.sql (initial schema script)
• Dockerfile + docker-compose.yml + .env_example (container definitions)
• Tests mirror controller and service packages under src/test
README for additional insights
• Confirms technologies: Spring Boot, MySQL, Swagger, JUnit, Mockito.
• Describes endpoints, Docker workflow, manual DB setup, and testing strategy.
Main components
a. Client(s)
• HTTP client (Postman, browser, CLI)
• Swagger UI (hosted at /swagger-ui.html)
b. API Layer
• PessoaController: handles HTTP requests/responses
c. Service Layer
• PessoaService: contains CRUD business logic, throws custom exceptions
d. Data Access Layer
• PessoaRepository: Spring Data JPA interface for MySQL
e. Database
• MySQL container (port 3306), schema initialized via init.sql or Flyway
f. Infrastructure
• Docker daemon + Docker Compose orchestrates two containers (app + DB)
• Environment variables from .env
g. Configuration & Cross-Cutting
• WebConfig (CORS, message converters)
• SwaggerConfig (API docs)
• GlobalExceptionHandles (error mapping)
Relationships and data flow
1. Client → HTTP request → Controller
2. Controller → DTO mapping → Service
3. Service → Repository calls → Database
4. Database → SQL results → Repository → Service → Controller → Client
5. Swagger UI as a special client consuming the same Controller endpoints
6. Docker Compose links the API container to the MySQL container over a private network
Architectural patterns and design principles
• Layered (onion) architecture: Controller → Service → Repository → DB
• Repository pattern via Spring Data JPA
• DTO pattern decouples API schema from entity model
• Global exception handling for consistent error responses
• Containerization for environment parity
Detail
• Init/init.sql or Flyway migration as part of DB initialization.
• Call out custom exceptions and the GlobalExceptionHandles component to indicate error-handling flow.