# tdb-plataformaraizdobem/raiz-do-bem-api architecture

> Architecture diagram of the GitHub repository tdb-plataformaraizdobem/raiz-do-bem-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tdb-plataformaraizdobem/raiz-do-bem-api
- Repository: https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api

## Overview

Raiz do Bem is a REST backend for beneficiary and social-aid administration, dental-care coordination, staff, addresses, and social programs. Its central workflow receives an aid request, processes approval, creates a beneficiary, then creates and closes dental appointments. README describes the resource/service/repository layering and broader endpoints; sampled services confirm key domain calls, persistence access, ViaCEP lookup, and Google Maps distance selection. Resource wiring and some documented subsystems are represented at directory level because their implementations were not sampled.

Main entry points: [`src/main/java/br/com/raizdobem/api/resource`](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/resource) (REST resources), [`src/main/java/br/com/raizdobem/api/repository`](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/repository) (Panache repositories), [`src/main/java/br/com/raizdobem/api/service/BeneficiarioService.java`](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/BeneficiarioService.java) (Beneficiaries), [`src/main/java/br/com/raizdobem/api/service/AtendimentoService.java`](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/AtendimentoService.java) (Dental appointments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_resources["REST resources"]
  node_requests["Request DTOs"]
  node_responses["Response DTOs"]
end

subgraph group_domain["Domain workflows"]
  node_aid["Aid requests"]
  node_beneficiaries["Beneficiaries"]
  node_appointments["Dental appointments"]
  node_dentists["Dentist management"]
  node_matching["Dentist matching"]
  node_staff["Staff management"]
  node_addresses["Address services"]
  node_programs["Social programs"]
  node_login["Login service<br/>[LoginService.java]"]
end

subgraph group_data["Persistence"]
  node_entities["Domain entities"]
  node_repositories["Panache repositories"]
  node_oracle[("Oracle database")]
end

subgraph group_integrations["External services"]
  node_viacep["ViaCEP"]
  node_viacepclient["ViaCEP client<br/>[ViaCepClient.java]"]
  node_maps["Google Maps"]
  node_mapsservice["Maps routing"]
  node_mapsclient["Maps client"]
end

subgraph group_support["Shared support"]
  node_mappers["DTO mappers"]
  node_errors["Exception handling"]
end

node_users(("API clients"))

node_users -->|"calls"| node_resources
node_resources -->|"dispatches"| node_aid
node_resources -->|"dispatches"| node_beneficiaries
node_resources -->|"dispatches"| node_appointments
node_resources -->|"dispatches"| node_dentists
node_resources -->|"dispatches"| node_addresses
node_resources -->|"dispatches"| node_staff
node_resources -->|"dispatches"| node_programs
node_resources -->|"dispatches"| node_login
node_resources -->|"accepts"| node_requests
node_resources -->|"returns"| node_responses
node_aid -->|"creates on approval"| node_beneficiaries
node_aid -->|"checks approver"| node_dentists
node_beneficiaries -->|"reads request"| node_aid
node_beneficiaries -->|"looks up program"| node_programs
node_beneficiaries -->|"updates address"| node_addresses
node_appointments -->|"selects dentist"| node_matching
node_appointments -->|"loads beneficiary"| node_beneficiaries
node_appointments -->|"loads dentist"| node_dentists
node_appointments -->|"assigns staff"| node_staff
node_matching -.->|"finds proximity"| node_mapsservice
node_mapsservice -->|"requests routes"| node_mapsclient
node_mapsclient -->|"queries distances"| node_maps
node_addresses -->|"looks up CEP"| node_viacepclient
node_viacepclient -->|"queries address"| node_viacep
node_aid -->|"persists and queries"| node_repositories
node_beneficiaries -->|"persists and queries"| node_repositories
node_appointments -->|"persists and queries"| node_repositories
node_dentists -->|"persists and queries"| node_repositories
node_staff -->|"persists and queries"| node_repositories
node_addresses -->|"persists and queries"| node_repositories
node_programs -->|"queries"| node_repositories
node_repositories -->|"loads and stores"| node_entities
node_repositories -->|"reads and writes"| node_oracle
node_aid -->|"maps responses"| node_mappers
node_beneficiaries -->|"maps responses"| node_mappers
node_appointments -->|"maps responses"| node_mappers
node_dentists -->|"maps responses"| node_mappers
node_addresses -->|"maps responses"| node_mappers
node_resources -->|"formats failures"| node_errors

click node_resources "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/resource"
click node_requests "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/dto/request"
click node_responses "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/dto/response"
click node_aid "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/PedidoAjudaService.java"
click node_beneficiaries "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/BeneficiarioService.java"
click node_appointments "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/AtendimentoService.java"
click node_dentists "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/DentistaService.java"
click node_matching "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/AtendimentoMatchService.java"
click node_staff "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/ColaboradorService.java"
click node_addresses "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/EnderecoService.java"
click node_programs "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/ProgramaService.java"
click node_login "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/LoginService.java"
click node_entities "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/entity"
click node_repositories "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/repository"
click node_mappers "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/mapper"
click node_errors "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/exception"
click node_viacepclient "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/client/ViaCepClient.java"
click node_mapsservice "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/GoogleMapsService.java"
click node_mapsclient "https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/client/GoogleMapsClient.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_resources,node_requests,node_responses,node_users toneBlue
class node_aid,node_beneficiaries,node_appointments,node_dentists,node_matching,node_staff,node_addresses,node_programs,node_login toneAmber
class node_entities,node_repositories,node_oracle toneMint
class node_viacep,node_viacepclient,node_maps,node_mapsservice,node_mapsclient toneRose
class node_mappers,node_errors toneIndigo
```

## Components

### REST API

- [REST resources](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/resource): `src/main/java/br/com/raizdobem/api/resource`
- [Request DTOs](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/dto/request): `src/main/java/br/com/raizdobem/api/dto/request`
- [Response DTOs](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/dto/response): `src/main/java/br/com/raizdobem/api/dto/response`

### Domain workflows

- [Aid requests](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/PedidoAjudaService.java): `src/main/java/br/com/raizdobem/api/service/PedidoAjudaService.java`
- [Beneficiaries](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/BeneficiarioService.java): `src/main/java/br/com/raizdobem/api/service/BeneficiarioService.java`
- [Dental appointments](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/AtendimentoService.java): `src/main/java/br/com/raizdobem/api/service/AtendimentoService.java`
- [Dentist management](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/DentistaService.java): `src/main/java/br/com/raizdobem/api/service/DentistaService.java`
- [Dentist matching](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/AtendimentoMatchService.java): `src/main/java/br/com/raizdobem/api/service/AtendimentoMatchService.java`
- [Staff management](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/ColaboradorService.java): `src/main/java/br/com/raizdobem/api/service/ColaboradorService.java`
- [Address services](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/EnderecoService.java): `src/main/java/br/com/raizdobem/api/service/EnderecoService.java`
- [Social programs](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/ProgramaService.java): `src/main/java/br/com/raizdobem/api/service/ProgramaService.java`
- [Login service](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/LoginService.java): `src/main/java/br/com/raizdobem/api/service/LoginService.java`

### Persistence

- [Domain entities](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/entity): `src/main/java/br/com/raizdobem/api/entity`
- [Panache repositories](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/repository): `src/main/java/br/com/raizdobem/api/repository`
- **Oracle database**

### External services

- **ViaCEP**
- [ViaCEP client](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/client/ViaCepClient.java): `src/main/java/br/com/raizdobem/api/client/ViaCepClient.java`
- **Google Maps**
- [Maps routing](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/service/GoogleMapsService.java): `src/main/java/br/com/raizdobem/api/service/GoogleMapsService.java`
- [Maps client](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/blob/main/src/main/java/br/com/raizdobem/api/client/GoogleMapsClient.java): `src/main/java/br/com/raizdobem/api/client/GoogleMapsClient.java`

### Shared support

- [DTO mappers](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/mapper): `src/main/java/br/com/raizdobem/api/mapper`
- [Exception handling](https://github.com/tdb-plataformaraizdobem/raiz-do-bem-api/tree/main/src/main/java/br/com/raizdobem/api/exception): `src/main/java/br/com/raizdobem/api/exception`

### Other components

- **API clients**

## Connections

- API clients → REST resources: calls
- REST resources → Aid requests: dispatches
- REST resources → Beneficiaries: dispatches
- REST resources → Dental appointments: dispatches
- REST resources → Dentist management: dispatches
- REST resources → Address services: dispatches
- REST resources → Staff management: dispatches
- REST resources → Social programs: dispatches
- REST resources → Login service: dispatches
- REST resources → Request DTOs: accepts
- REST resources → Response DTOs: returns
- Aid requests → Beneficiaries: creates on approval
- Aid requests → Dentist management: checks approver
- Beneficiaries → Aid requests: reads request
- Beneficiaries → Social programs: looks up program
- Beneficiaries → Address services: updates address
- Dental appointments → Dentist matching: selects dentist
- Dental appointments → Beneficiaries: loads beneficiary
- Dental appointments → Dentist management: loads dentist
- Dental appointments → Staff management: assigns staff
- Dentist matching → Maps routing: finds proximity
- Maps routing → Maps client: requests routes
- Maps client → Google Maps: queries distances
- Address services → ViaCEP client: looks up CEP
- ViaCEP client → ViaCEP: queries address
- Aid requests → Panache repositories: persists and queries
- Beneficiaries → Panache repositories: persists and queries
- Dental appointments → Panache repositories: persists and queries
- Dentist management → Panache repositories: persists and queries
- Staff management → Panache repositories: persists and queries
- Address services → Panache repositories: persists and queries
- Social programs → Panache repositories: queries
- Panache repositories → Domain entities: loads and stores
- Panache repositories → Oracle database: reads and writes
- Aid requests → DTO mappers: maps responses
- Beneficiaries → DTO mappers: maps responses
- Dental appointments → DTO mappers: maps responses
- Dentist management → DTO mappers: maps responses
- Address services → DTO mappers: maps responses
- REST resources → Exception handling: formats failures