How kimmorais/desafio-back-votos works
Project Overview & Components
• Project Type: This is a REST API backend for a voting system in assemblies. It’s built using Java 17 and Spring Boot. The API deals with operations like creating “pautas” (agenda items), registering “associados” (associates), starting assemblies, handling votes, and providing results.
• Key Modules: The project is split into two main Maven modules:
• back_votos_core: Contains the core domain logic, entities, use cases and business rules.
• back_votos_plugins: Acts as an adapter layer which handles API endpoints (REST controllers), external integrations (e.g., database access layers, messaging), scheduling and configuration.
• External Services & Infrastructure:
• AWS Elastic Beanstalk is used to run the API.
• AWS RDS (PostgreSQL) for persistent data.
• AWS SQS for messaging (with scheduled tasks publishing messages to the SQS queue).
• The project uses Docker Compose (in resources) for local testing setups.
Analyzing the File Structure
• The back_votos_core module follows a clean code/hexagonal architecture style:
• Directories like “entities”, “use_cases” and “contratos” indicate a separation between domain entities, business logic use cases and interfaces/ports.
• Factories, input models, and implementation directories provide clear boundaries between the domain and its instantiation.
• The presence of tests for each use case reinforces that each component is well-isolated for unit testing.
• The back_votos_plugins module:
• Contains REST endpoint controllers (e.g., “CadastrarAssociadoUseCaseRestEndpoint”), request models and adapter classes to translate between the REST layer and core business use cases.
• Has Data Access Object (DAO) repositories and table mappers for database interactions.
• Also implements scheduling mechanisms to periodically check and process closed assemblies, involving SQS (“publisher” and “subscriber” packages).
a. Main Components:
• API Clients: External client applications (Postman, browser, etc.) that call the REST API.
• REST API Layer (back_votos_plugins):
• REST Controllers/Endpoints (e.g., endpoints for ‘cadastrar_associado’, ‘cadastrar_pauta’, ‘iniciar_assembleia’, ‘votar’, and ‘obter_resultado_assembleia’).
• Request Models and Port Adapters: Translate the incoming requests to a format consumable by use cases.
• Core Business Logic (back_votos_core):
• Use Cases: Organized by functionality (cadastrar_associado, iniciar_assembleia, votar etc.) handling business validations.
• Domain Entities & Factories: (e.g., Assembleia, Associado, Pauta, Voto with their respective implementations and factories).
• Contract Interfaces/Ports: Abstractions for data persistence or external operations.
• Data Access & Persistence Layer:
• DAO Repositories and Table Mappers in the plugins module to interact with the PostgreSQL database in AWS RDS.
• Messaging & Scheduling:
• Scheduler component (Spring Cron jobs) that every 30 minutes checks for assemblies that are finished.
• Publisher (and corresponding Subscriber) that sends/receives messages to/from AWS SQS.
• External Infrastructure:
• AWS Elastic Beanstalk for hosting the API.
• AWS RDS for PostgreSQL.
• AWS SQS for message queuing.
b. Relationships & Interactions:
• Clients make HTTP requests → API endpoints in back_votos_plugins.
• Endpoints forward the requests via their use case provider adapters to the core use cases in back_votos_core.
• Use cases perform validations and business logic, then interact with repository interfaces defined as ports.
• The data access layer in plugins implements these repository ports to perform CRUD operations on the PostgreSQL database.
• Scheduled tasks (using the Spring Scheduler) periodically invoke logic to check assembly statuses and trigger the SQS publisher.
• The messaging flow: Publisher sends messages to AWS SQS, and a subscriber component in the application (or another service) consumes these messages.
c. Architectural Patterns & Design Principles:
• Hexagonal/Ports-and-Adapters Architecture: The clear separation between “core” (business logic) and “adapters” (REST endpoints, database access, messaging).
• Domain-Driven Design: Entities, use cases and factories closely mirror real-world voting processes.
• Separation of Concerns: Controllers, use cases, data persistence and messaging are each encapsulated in their own packages.
d. Relevant Technologies & Frameworks:
• Java 17, Spring Boot for application framework.
• JUnit 5 and Mockito for unit testing.
• Maven for dependency and build management.
• AWS services (Elastic Beanstalk, RDS, SQS).
• PostgreSQL as the relational database.
• Docker Compose (for local dev environments).
Emphasizing Detail
• Element (both core modules and plugins) is clearly separated.
• Use of factories and adapters, showing the conversion between API models and internal domain models.
• Error handling paths or alternative flows where appropriate (e.g., validations in voting process like “AssociadoNaoPodeVotarException”).