How henriquegsena/cep-manager works
Project type and purpose
• This is a full-stack web application for CEP lookup and address/user management.
• Frontend: React + Tailwind/shadCN + react-query + axios.
• Backend: Spring Boot (REST API) + WebFlux (for external HTTP client) + JPA + Liquibase + PostgreSQL.
• External service: ViaCEP API for address lookup.
File structure
• Top level:
• cepManagerServer/ – Java backend
• web-app/ – React frontend
• Backend sub-structure follows typical Spring Boot conventions:
• config/ – CORS, Swagger, WebClient (ViaCEP)
• controller/ – REST endpoints (CepController, UsuarioController)
• service/ – business logic (CepService, UsuariosService)
• repository/ – JPA repositories (UsuariosRepository)
• entities/, dto/, exceptions/
• resources/ – application.yml, Liquibase changelogs, Docker Compose for Postgres
• Frontend sub-structure:
• src/components – UI layout (DataTable, RegisterDialog, SearchBar) + primitives (button, dialog, input, label, pagination, table)
• src/hooks – React Query hooks for CRUD and ViaCEP lookup
• src/lib – API client (axios) and utilities
• Vite config + TypeScript setup
README for additional insights
• Describes CRUD operations, integration with ViaCEP, database persistence, Swagger UI for API docs, Docker Compose.
• Technology stack: React, shadCN, react-query, axios; Spring Boot, Liquibase, PostgreSQL.
a. Main components
– Browser/Client (React app)
– API Gateway (Spring Boot REST controllers)
– Business Services (CepService, UsuariosService)
– Persistence Layer (JPA → PostgreSQL)
– External Service (ViaCEP HTTP API)
– DevOps/infra: Docker Compose for Postgres, Swagger UI
b. Relationships and interactions
1. User interacts with React UI → form input triggers react-query hooks → axios HTTP calls to Spring Boot.
2. Spring Boot controllers route requests to service layer.
3. CepService calls ViaCEP via WebClient (configured in WebClientConfig).
4. UsersService interacts with UsuariosRepository (Spring Data JPA) → PostgreSQL.
5. Liquibase changelogs manage DB schema on startup.
6. Swagger UI auto-generates API docs on /swagger-ui/index.html.
7. Docker Compose spins up Postgres container for local development.
c. Architectural patterns and design principles
– Layered architecture (Controller → Service → Repository)
– DTOs for payload mapping
– Exception handling via GlobalExceptionHandler
– Configuration-driven (application.yml profiles)
– External integration via reactive WebClient
– Client-side caching and mutations via React Query
d. Key technologies/frameworks
– Frontend: React, TypeScript, Vite, shadCN/Tailwind, React Query, Axios
– Backend: Spring Boot Web MVC + WebFlux, Spring Data JPA, Lombok, Liquibase, PostgreSQL, Swagger (springdoc)
– Infra: Docker Compose, Maven wrapper
Final advice
• Be detailed but avoid clutter: represent each logical layer/component.
• Document environment setups (e.g., Docker Compose for Postgres) as side notes or infra layer.