# genissonemilio/coleta-seletiva-backend architecture

> Architecture diagram of the GitHub repository genissonemilio/coleta-seletiva-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/genissonemilio/coleta-seletiva-backend
- Repository: https://github.com/genissonemilio/coleta-seletiva-backend

## Overview

Coleta Seletiva is a Spring API connecting residents, collection points, recyclable materials, and collection operators. The principal workflow is a client request to manage or consult collection points and materials, or submit and progress a pickup request; records are persisted in PostgreSQL. The README documents actor-selection headers for local demonstrations, not production authentication. Core service-to-repository and pagination links are supported by sampled source/index references; several controller and domain-service links are shown as unverified because those implementations were not excerpted.

Main entry points: [`coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/ponto/PontoService.java`](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/ponto/PontoService.java) (Point management), [`coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/ColetaSeletivaApiApplication.java`](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/ColetaSeletivaApiApplication.java) (Spring application), [`coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/ContextoController.java`](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/ContextoController.java) (Actor context), [`coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/ContextoService.java`](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/ContextoService.java) (Context resolver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and context"]
  node_application["Spring application"]
  node_context_controller["Actor context"]
  node_context_service["Context resolver"]
  node_demo["Demo actors"]
end

subgraph group_catalog["Collection catalog"]
  node_point_controller["Point endpoints"]
  node_point_service["Point management<br/>[PontoService.java]"]
  node_point_material["Accepted materials"]
  node_material_controller["Material endpoints"]
  node_material_service["Material management"]
  node_resident["Resident records"]
  node_operator["Operator records"]
end

subgraph group_requests["Pickup requests"]
  node_request_controller["Pickup endpoints"]
  node_request_service["Pickup lifecycle"]
end

subgraph group_insights["Consultation and indicators"]
  node_public_controller["Public endpoints"]
  node_public_service["Public lookup"]
  node_indicator["Collection indicators"]
end

subgraph group_persistence["Persistence and shared rules"]
  node_database[("PostgreSQL")]
  node_point_repository["Point queries"]
  node_resident_repository["Resident queries"]
  node_pagination["Pagination rules"]
  node_errors["API error handling"]
end

node_client(("API client"))

node_client -->|"sends HTTP"| node_application
node_application -.->|"persists data"| node_database
node_client -->|"selects actor"| node_context_controller
node_context_controller -.->|"resolves context"| node_context_service
node_context_service -->|"looks up resident"| node_resident_repository
node_client -.->|"manages points"| node_point_controller
node_point_controller -.->|"delegates"| node_point_service
node_point_service -->|"queries and saves"| node_point_repository
node_point_service -->|"builds pages"| node_pagination
node_client -.->|"manages materials"| node_material_controller
node_material_controller -.->|"delegates"| node_material_service
node_material_service -->|"builds pages"| node_pagination
node_client -.->|"submits pickup"| node_request_controller
node_request_controller -.->|"delegates"| node_request_service
node_client -.->|"searches points"| node_public_controller
node_public_controller -.->|"delegates"| node_public_service
node_client -.->|"requests metrics"| node_indicator
node_demo -.->|"seeds demo actors"| node_database
node_point_material -.->|"stores point links"| node_database
node_resident -.->|"stores residents"| node_database
node_operator -.->|"stores operators"| node_database
node_request_service -.->|"stores requests"| node_database
node_public_service -.->|"searches active points"| node_point_repository
node_errors -.->|"formats errors"| node_client

click node_application "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/ColetaSeletivaApiApplication.java"
click node_context_controller "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/ContextoController.java"
click node_context_service "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/ContextoService.java"
click node_demo "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/DadosDemoService.java"
click node_point_controller "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/PontoController.java"
click node_point_service "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/ponto/PontoService.java"
click node_point_material "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/pontomaterial/PontoMaterialService.java"
click node_material_controller "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/MaterialController.java"
click node_material_service "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/material/MaterialService.java"
click node_resident "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/morador/MoradorService.java"
click node_operator "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/operador/OperadorService.java"
click node_request_controller "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/SolicitacaoController.java"
click node_request_service "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/solicitacao/SolicitacaoService.java"
click node_public_controller "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/ConsultaPublicaController.java"
click node_public_service "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/publico/ConsultaPublicaService.java"
click node_indicator "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/indicador/IndicadorService.java"
click node_point_repository "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/repository/PontoRepository.java"
click node_resident_repository "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/repository/MoradorRepository.java"
click node_pagination "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/paginacao/PaginacaoService.java"
click node_errors "https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/exception/GlobalExceptionHandler.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_application,node_context_controller,node_context_service,node_demo,node_client toneBlue
class node_point_controller,node_point_service,node_point_material,node_material_controller,node_material_service,node_resident,node_operator toneAmber
class node_request_controller,node_request_service toneMint
class node_public_controller,node_public_service,node_indicator toneRose
class node_database,node_point_repository,node_resident_repository,node_pagination,node_errors toneIndigo
```

## Components

### API and context

- [Spring application](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/ColetaSeletivaApiApplication.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/ColetaSeletivaApiApplication.java`
- [Actor context](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/ContextoController.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/ContextoController.java`
- [Context resolver](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/ContextoService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/ContextoService.java`
- [Demo actors](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/DadosDemoService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/DadosDemoService.java`

### Collection catalog

- [Point endpoints](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/PontoController.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/PontoController.java`
- [Point management](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/ponto/PontoService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/ponto/PontoService.java`
- [Accepted materials](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/pontomaterial/PontoMaterialService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/pontomaterial/PontoMaterialService.java`
- [Material endpoints](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/MaterialController.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/MaterialController.java`
- [Material management](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/material/MaterialService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/material/MaterialService.java`
- [Resident records](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/morador/MoradorService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/morador/MoradorService.java`
- [Operator records](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/operador/OperadorService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/operador/OperadorService.java`

### Pickup requests

- [Pickup endpoints](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/SolicitacaoController.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/SolicitacaoController.java`
- [Pickup lifecycle](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/solicitacao/SolicitacaoService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/solicitacao/SolicitacaoService.java`

### Consultation and indicators

- [Public endpoints](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/ConsultaPublicaController.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/ConsultaPublicaController.java`
- [Public lookup](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/publico/ConsultaPublicaService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/publico/ConsultaPublicaService.java`
- [Collection indicators](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/indicador/IndicadorService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/indicador/IndicadorService.java`

### Persistence and shared rules

- **PostgreSQL**
- [Point queries](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/repository/PontoRepository.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/repository/PontoRepository.java`
- [Resident queries](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/repository/MoradorRepository.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/repository/MoradorRepository.java`
- [Pagination rules](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/paginacao/PaginacaoService.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/paginacao/PaginacaoService.java`
- [API error handling](https://github.com/genissonemilio/coleta-seletiva-backend/blob/main/coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/exception/GlobalExceptionHandler.java): `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/exception/GlobalExceptionHandler.java`

### Other components

- **API client**

## Connections

- API client → Spring application: sends HTTP (evidence: `README.md`)
- Spring application → PostgreSQL: persists data (evidence: `README.md`)
- API client → Actor context: selects actor (evidence: `README.md`)
- Actor context → Context resolver: resolves context
- Context resolver → Resident queries: looks up resident (evidence: `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/contexto/ContextoService.java`)
- API client → Point endpoints: manages points
- Point endpoints → Point management: delegates (evidence: `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/PontoController.java`)
- Point management → Point queries: queries and saves (evidence: `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/ponto/PontoService.java`)
- Point management → Pagination rules: builds pages (evidence: `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/ponto/PontoService.java`)
- API client → Material endpoints: manages materials
- Material endpoints → Material management: delegates (evidence: `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/MaterialController.java`)
- Material management → Pagination rules: builds pages (evidence: `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/material/MaterialService.java`)
- API client → Pickup endpoints: submits pickup
- Pickup endpoints → Pickup lifecycle: delegates (evidence: `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/controller/SolicitacaoController.java`)
- API client → Public endpoints: searches points
- Public endpoints → Public lookup: delegates
- API client → Collection indicators: requests metrics
- Demo actors → PostgreSQL: seeds demo actors (evidence: `README.md`)
- Accepted materials → PostgreSQL: stores point links
- Resident records → PostgreSQL: stores residents
- Operator records → PostgreSQL: stores operators
- Pickup lifecycle → PostgreSQL: stores requests
- Public lookup → Point queries: searches active points (evidence: `coleta-seletiva-api/src/main/java/br/edu/ifs/web1/coletaseletiva/services/publico/ConsultaPublicaService.java`)
- API error handling → API client: formats errors
