# kimmorais/desafio-back-votos architecture

> Architecture diagram of the GitHub repository kimmorais/desafio-back-votos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kimmorais/desafio-back-votos
- Repository: https://github.com/kimmorais/desafio-back-votos

## Overview

##### 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”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients"
        Client["API Client (Postman,Browser)"]:::client
    end

    subgraph "Presentation Layer (REST API Endpoints - back_votos_plugins)"
        CA_Endpoint["CadastrarAssociado Endpoint"]:::api
        CP_Endpoint["CadastrarPauta Endpoint"]:::api
        IA_Endpoint["IniciarAssembleia Endpoint"]:::api
        OR_Endpoint["ObterResultadoAssembleia Endpoint"]:::api
        V_Endpoint["Votar Endpoint"]:::api
    end

    subgraph "Use Case Providers / Adapters (back_votos_plugins)"
        CA_Provider["CadastrarAssociado UseCase Provider"]:::adapter
        CP_Provider["CadastrarPauta UseCase Provider"]:::adapter
        IA_Provider["IniciarAssembleia UseCase Provider"]:::adapter
        OR_Provider["ObterResultadoAssembleia UseCase Provider"]:::adapter
        V_Provider["Votar UseCase Provider"]:::adapter
    end

    subgraph "Dependency Management (back_votos_plugins)"
        Factories["Factories & Dependency Management"]:::adapter
    end

    subgraph "Core Business Logic (back_votos_core)"
        CA_UseCase["CadastrarAssociado Use Case"]:::core
        CP_UseCase["CadastrarPauta Use Case"]:::core
        IA_UseCase["IniciarAssembleia Use Case"]:::core
        OR_UseCase["ObterResultadoAssembleia Use Case"]:::core
        V_UseCase["Votar Use Case"]:::core
        Domain["Domain Entities & Factories"]:::domain
    end

    subgraph "Persistence & Data Access Layer"
        Persistence["DAO Repositories & Table Mappers"]:::persistence
    end

    subgraph "Messaging & Scheduling"
        Scheduler["Scheduler (Spring Cron)"]:::messaging
        Publisher["AWS SQS Publisher"]:::messaging
        Subscriber["AWS SQS Subscriber"]:::messaging
    end

    subgraph "AWS Infrastructure"
        AWS_EB["AWS Elastic Beanstalk (Hosting API)"]:::aws
        AWS_RDS["AWS RDS (PostgreSQL)"]:::aws
        AWS_SQS["AWS SQS (Message Queue)"]:::aws
    end

    %% Connections from External Clients to REST Endpoints
    Client -->|"HTTP_Request"| CA_Endpoint
    Client -->|"HTTP_Request"| CP_Endpoint
    Client -->|"HTTP_Request"| IA_Endpoint
    Client -->|"HTTP_Request"| OR_Endpoint
    Client -->|"HTTP_Request"| V_Endpoint

    %% REST Endpoints call Use Case Providers
    CA_Endpoint -->|"calls"| CA_Provider
    CP_Endpoint -->|"calls"| CP_Provider
    IA_Endpoint -->|"calls"| IA_Provider
    OR_Endpoint -->|"calls"| OR_Provider
    V_Endpoint -->|"calls"| V_Provider

    %% Use Case Providers invoke Core Business Logic
    CA_Provider -->|"invokes"| CA_UseCase
    CP_Provider -->|"invokes"| CP_UseCase
    IA_Provider -->|"invokes"| IA_UseCase
    OR_Provider -->|"invokes"| OR_UseCase
    V_Provider -->|"invokes"| V_UseCase

    %% Core Business Logic utilizes Domain Entities & Factories
    CA_UseCase -->|"utilizes"| Domain
    CP_UseCase -->|"utilizes"| Domain
    IA_UseCase -->|"utilizes"| Domain
    OR_UseCase -->|"utilizes"| Domain
    V_UseCase -->|"utilizes"| Domain

    %% Business Logic interacts with Persistence Layer
    CA_UseCase -->|"CRUD"| Persistence
    CP_UseCase -->|"CRUD"| Persistence
    IA_UseCase -->|"CRUD"| Persistence
    OR_UseCase -->|"CRUD"| Persistence
    V_UseCase -->|"CRUD"| Persistence

    %% Messaging & Scheduling interactions
    Scheduler -->|"triggers"| Publisher
    Publisher -->|"sends_msg"| AWS_SQS
    AWS_SQS -->|"consumed_by"| Subscriber

    %% AWS Infrastructure hosting connections
    AWS_EB -->|"hosts"| CA_Endpoint
    AWS_EB -->|"hosts"| CP_Endpoint
    AWS_EB -->|"hosts"| IA_Endpoint
    AWS_EB -->|"hosts"| OR_Endpoint
    AWS_EB -->|"hosts"| V_Endpoint

    Persistence -->|"stores_data_in"| AWS_RDS

    %% Class definitions for colors
    classDef client fill:#f7f7a1,stroke:#333,stroke-width:2px;
    classDef api fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef adapter fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef core fill:#c3f584,stroke:#333,stroke-width:2px;
    classDef domain fill:#d7bde2,stroke:#333,stroke-width:2px;
    classDef persistence fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef messaging fill:#fadadd,stroke:#333,stroke-width:2px;
    classDef aws fill:#d1eeee,stroke:#333,stroke-width:2px;

    %% Click Events for REST API Endpoints
    click CA_Endpoint "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/cadastrar_associado/rest_endpoint/CadastrarAssociadoUseCaseRestEndpoint.java"
    click CP_Endpoint "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/cadastrar_pauta/rest_endpoint/CadastrarPautaUseCaseRestEndpoint.java"
    click IA_Endpoint "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/iniciar_assembleia/rest_endpoint/IniciarAssembleiaUseCaseRestEndpoint.java"
    click OR_Endpoint "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/obter_resultado_assembleia/rest_endpoint/ObterResultadoAssembleiaRestEndpoint.java"
    click V_Endpoint "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/votar/rest_endpoint/VotarUseCaseRestEndpoint.java"

    %% Click Events for Use Case Providers
    click CA_Provider "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/cadastrar_associado/use_case_provider/CadastrarAssociadoUseCaseProvider.java"
    click CP_Provider "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/cadastrar_pauta/use_case_provider/CadastrarPautaUseCaseProvider.java"
    click IA_Provider "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/iniciar_assembleia/use_case_provider/IniciarAssembleiaUseCaseProvider.java"
    click OR_Provider "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/obter_resultado_assembleia/use_case_provider/ObterResultadoAssembleiaUseCaseProvider.java"
    click V_Provider "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/votar/use_case_provider/VotarUseCaseProvider.java"

    %% Click Event for Dependency Management / Factories
    click Factories "https://github.com/kimmorais/desafio-back-votos/tree/main/back_votos_plugins/src/main/java/org/back_votos_plugins/factories"

    %% Click Events for Core Business Logic and Domain Entities
    click Domain "https://github.com/kimmorais/desafio-back-votos/tree/main/back_votos_core/src/main/java/org/back_votos_core/entities"

    %% Click Event for Persistence Layer (Repositories)
    click Persistence "https://github.com/kimmorais/desafio-back-votos/tree/main/back_votos_plugins/src/main/java/org/back_votos_plugins/dao/repositories"

    %% Click Events for Messaging & Scheduling Components
    click Publisher "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/obter_resultado_assembleia/scheduling/publisher/ObterResultadoAssembleiaPublisher.java"
    click Subscriber "https://github.com/kimmorais/desafio-back-votos/blob/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/obter_resultado_assembleia/scheduling/subscriber/ObterResultadoAssembleiaSubscriber.java"
    click Scheduler "https://github.com/kimmorais/desafio-back-votos/tree/main/back_votos_plugins/src/main/java/org/back_votos_plugins/use_cases/obter_resultado_assembleia/scheduling"
```
