# fuhr-br/cadastro architecture

> Architecture diagram of the GitHub repository fuhr-br/cadastro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fuhr-br/cadastro
- Repository: https://github.com/fuhr-br/cadastro

## Overview

##### Project type and purpose
- This is a monolithic, layered REST‐API built with Java Spring Boot.
- It manages “Pessoa” (person) and “Endereco” (address) entities: create/read/update operations, designate a primary address, and list records.

##### File structure
- Top-level: pom.xml, Maven wrapper, .github/workflows (CI with GitHub Actions), README.
- src/main/java/com/attornatus/cadastro:
- CadastroApplication.java – Spring Boot entrypoint
- controller/ – REST controllers (PessoaController)
- service/ – business logic (PessoaService, EnderecoService)
- infra/ – repositories (PessoaRepository, EnderecoRepository)
- domain/ – JPA entities (Pessoa, Endereco)
- dto/ – request/response DTO classes
- mapper/ – MapStruct or manual mappers (PessoaMapper, EnderecoMapper)
- exception/ & handler/ – exception types and global error handler
- src/main/resources: application.properties (H2 config, Swagger)
- src/test: unit & integration tests (MockMvc, in-memory H2, SQL scripts)

##### README for additional insights
- Uses H2 in-memory DB
- Exposes Swagger UI (/swagger-ui) and H2 console
- CI & CD via GitHub Actions and Heroku deployment
- Emphasis on clean code, test coverage, layered architecture

a. Main components:
- Client / API consumer (e.g., Swagger UI, Postman)
- REST Controller layer (handles HTTP requests)
- Service layer (business rules)
- Mapper layer (converts between domain and DTO)
- Repository layer (Spring Data JPA interacting with H2 DB)
- H2 Database (in-memory)
- Exception Handler (intercepts and formats errors)
- External services: Swagger‐UI, H2 console, CI/CD pipeline (GitHub Actions → Heroku)
b. Relationships & data flow:
Client → Controller → Service → Repository → H2 DB
Repository returns entities → Mapper → Service → Controller → JSON response
Exception thrown in any layer → RestExceptionHandler → JSON error payload
c. Architectural patterns & principles:
- Layered (Controller/Service/Repository)
- MVC-inspired REST
- DTO pattern with dedicated Mapper layer
- Repository pattern (via Spring Data JPA)
- Global exception handling (ControllerAdvice)
- In-memory DB for fast tests and demo
d. Key technologies:
- Java & Spring Boot
- Spring Web (REST controllers)
- Spring Data JPA (repositories)
- H2 Database
- Maven build & dependency management
- MapStruct or custom mappers
- Swagger UI for API documentation
- JUnit + MockMvc for testing
- GitHub Actions & Heroku for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients"
        Client["Client (Swagger UI / Postman)"]:::external
        SwaggerUI["Swagger UI"]:::external
        Client -->|"HTTP Request"| PessoaController
        SwaggerUI -->|"API Docs"| PessoaController
    end

    subgraph "Application Entry" 
        Entrypoint["CadastroApplication"]:::app
    end

    subgraph "Configuration"
        Config["application.properties"]:::config
    end

    subgraph "Controller Layer"
        PessoaController["PessoaController"]:::controller
    end

    subgraph "Service & Mapper Layer"
        PessoaService["PessoaService"]:::service
        EnderecoService["EnderecoService"]:::service
        PessoaMapper["PessoaMapper"]:::mapper
        EnderecoMapper["EnderecoMapper"]:::mapper
    end

    subgraph "Persistence Layer"
        PessoaRepository["PessoaRepository"]:::repository
        EnderecoRepository["EnderecoRepository"]:::repository
    end

    DB((H2 Database)):::database

    ExceptionHandler["RestExceptionHandler"]:::exception

    subgraph "CI/CD Pipeline"
        GH["GitHub Actions"]:::external
        Heroku["Heroku"]:::external
        GH -->|"Build/Test/Deploy"| Heroku
    end

    H2Console["H2 Console"]:::external

    subgraph "Testing"
        Tests["Unit & Integration Tests"]:::test
    end

    Entrypoint --> Config
    Entrypoint --> PessoaController
    PessoaController -->|"delegate"| PessoaService
    PessoaService -->|"uses"| PessoaMapper
    PessoaService -->|"calls"| EnderecoService
    EnderecoService -->|"uses"| EnderecoMapper
    PessoaService -->|"save()/find()"| PessoaRepository
    EnderecoService -->|"save()/find()"| EnderecoRepository
    PessoaRepository -->|"SQL"| DB
    EnderecoRepository -->|"SQL"| DB

    PessoaController -->|"errors"| ExceptionHandler
    PessoaService -->|"errors"| ExceptionHandler
    PessoaRepository -->|"errors"| ExceptionHandler

    SwaggerUI --> PessoaController
    H2Console --> DB
    Tests --> Config
    Tests --> DB

    GH -->|"triggers"| Tests

    click Entrypoint "https://github.com/fuhr-br/cadastro/blob/main/src/main/java/com/attornatus/cadastro/CadastroApplication.java"
    click PessoaController "https://github.com/fuhr-br/cadastro/blob/main/src/main/java/com/attornatus/cadastro/controller/PessoaController.java"
    click PessoaService "https://github.com/fuhr-br/cadastro/blob/main/src/main/java/com/attornatus/cadastro/service/PessoaService.java"
    click EnderecoService "https://github.com/fuhr-br/cadastro/blob/main/src/main/java/com/attornatus/cadastro/service/EnderecoService.java"
    click PessoaMapper "https://github.com/fuhr-br/cadastro/blob/main/src/main/java/com/attornatus/cadastro/mapper/PessoaMapper.java"
    click EnderecoMapper "https://github.com/fuhr-br/cadastro/blob/main/src/main/java/com/attornatus/cadastro/mapper/EnderecoMapper.java"
    click PessoaRepository "https://github.com/fuhr-br/cadastro/blob/main/src/main/java/com/attornatus/cadastro/infra/PessoaRepository.java"
    click EnderecoRepository "https://github.com/fuhr-br/cadastro/blob/main/src/main/java/com/attornatus/cadastro/infra/EnderecoRepository.java"
    click Config "https://github.com/fuhr-br/cadastro/blob/main/src/main/resources/application.properties"
    click GH "https://github.com/fuhr-br/cadastro/blob/main/.github/workflows/maven.yml"
    click Tests "https://github.com/fuhr-br/cadastro/tree/main/src/test/java/com/attornatus/cadastro"

    classDef external fill:#fdebd0,stroke:#d35400
    classDef controller fill:#d6eaf8,stroke:#2874a6
    classDef service fill:#d5f5e3,stroke:#239b56
    classDef mapper fill:#fcf3cf,stroke:#b7950b
    classDef repository fill:#f9ebea,stroke:#c0392b
    classDef database fill:#e8f8f5,stroke:#117864,stroke-dasharray:5 5
    classDef exception fill:#f5eef8,stroke:#7d3c98,stroke-dasharray:2 2
    classDef app fill:#e8f6f3,stroke:#1abc9c
    classDef config fill:#e9f7ef,stroke:#27ae60
    classDef test fill:#fdebd0,stroke:#b9770e
```
