# josealbertonp/api-pessoa architecture

> Architecture diagram of the GitHub repository josealbertonp/api-pessoa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josealbertonp/api-pessoa
- Repository: https://github.com/josealbertonp/api-pessoa

## Overview

##### Project type and purpose
- This is a monolithic, backend-only REST API built with Spring Boot (Java 17) that exposes CRUD operations on a Pessoa (Person) entity.
- It uses MySQL for persistence, is containerized via Docker/Docker Compose, and provides Swagger UI for interactive documentation.

##### File structure
- src/main/java/com/pessoa/apipessoa
- ApiPessoaApplication.java (entry point)
- controller/ (REST controllers)
- service/ (business logic)
- repository/ (Spring Data JPA interfaces)
- entity/ (JPA entities)
- DTOs/request + DTOs/response (data transfer objects)
- config/ (WebConfig, SwaggerConfig)
- exception/ (custom exceptions and global handler)
- src/main/resources/application.properties (DB and app settings)
- init/init.sql (initial schema script)
- Dockerfile + docker-compose.yml + .env_example (container definitions)
- Tests mirror controller and service packages under src/test

##### README for additional insights
- Confirms technologies: Spring Boot, MySQL, Swagger, JUnit, Mockito.
- Describes endpoints, Docker workflow, manual DB setup, and testing strategy.

##### Main components
a. Client(s)
- HTTP client (Postman, browser, CLI)
- Swagger UI (hosted at /swagger-ui.html)
b. API Layer
- PessoaController: handles HTTP requests/responses
c. Service Layer
- PessoaService: contains CRUD business logic, throws custom exceptions
d. Data Access Layer
- PessoaRepository: Spring Data JPA interface for MySQL
e. Database
- MySQL container (port 3306), schema initialized via init.sql or Flyway
f. Infrastructure
- Docker daemon + Docker Compose orchestrates two containers (app + DB)
- Environment variables from .env
g. Configuration & Cross-Cutting
- WebConfig (CORS, message converters)
- SwaggerConfig (API docs)
- GlobalExceptionHandles (error mapping)

##### Relationships and data flow
1. Client → HTTP request → Controller
2. Controller → DTO mapping → Service
3. Service → Repository calls → Database
4. Database → SQL results → Repository → Service → Controller → Client
5. Swagger UI as a special client consuming the same Controller endpoints
6. Docker Compose links the API container to the MySQL container over a private network

##### Architectural patterns and design principles
- Layered (onion) architecture: Controller → Service → Repository → DB
- Repository pattern via Spring Data JPA
- DTO pattern decouples API schema from entity model
- Global exception handling for consistent error responses
- Containerization for environment parity

##### Detail
- Init/init.sql or Flyway migration as part of DB initialization.
- Call out custom exceptions and the GlobalExceptionHandles component to indicate error-handling flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Consumers
    subgraph "API Consumers"
        direction TB
        HTTPClient["HTTP Client (Postman, Browser)"]:::external
        SwaggerUI["Swagger UI"]:::external
    end

    %% Docker Compose Environment
    subgraph "Docker Compose" 
        direction TB
        EnvExample[".env_example"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
        DockerfileNode["Dockerfile"]:::infra

        subgraph "api-pessoa (Container)" 
            direction TB
            ApiPessoaApplication["ApiPessoaApplication"]:::app
            ApplicationProperties["application.properties"]:::config
            WebConfigNode["WebConfig"]:::config
            SwaggerConfigNode["SwaggerConfig"]:::config
            GlobalExceptionHandles["GlobalExceptionHandles"]:::exception
            PessoaController["PessoaController"]:::controller
            PessoaService["PessoaService"]:::service
            PessoaRepository["PessoaRepository"]:::repository
            PessoaEntity["Pessoa (Entity)"]:::entity
            PessoaRequest["PessoaRequest (DTO)"]:::dto
            PessoaResponse["PessoaResponse (DTO)"]:::dto
            CpfJaCadastradoException["CpfJaCadastradoException"]:::exception
            NotFoundException["NotFoundException"]:::exception
        end

        subgraph "mysql (Container)"
            direction TB
            MySQLDB["MySQL Database"]:::database
            InitSQL["init.sql"]:::infra
        end
    end

    %% Tests
    subgraph "Automated Tests" 
        direction TB
        ControllerTest["PessoaControllerTest"]:::test
        ServiceTest["PessoaServiceTest"]:::test
        AppTest["ApiPessoaApplicationTests"]:::test
    end

    %% Flows
    HTTPClient -->|"HTTP Requests"| PessoaController
    SwaggerUI -->|"UI Requests"| PessoaController
    PessoaController -->|"validates/mapping"| PessoaRequest
    PessoaController -->|"calls"| PessoaService
    PessoaService -->|"business logic"| PessoaRepository
    PessoaRepository -->|"JPA CRUD"| MySQLDB
    MySQLDB -->|"results"| PessoaRepository
    PessoaRepository --> PessoaService
    PessoaService --> PessoaResponse
    PessoaResponse --> PessoaController
    PessoaController --> HTTPClient

    PessoaController -->|"throws"| CpfJaCadastradoException
    PessoaController -->|"throws"| NotFoundException
    CpfJaCadastradoException --> GlobalExceptionHandles
    NotFoundException --> GlobalExceptionHandles
    GlobalExceptionHandles --> PessoaController

    EnvExample -->|"env vars"| ApplicationProperties
    ApplicationProperties --> ApiPessoaApplication
    InitSQL --> MySQLDB

    %% Docker orchestrations
    DockerCompose --> api-pessoa
    DockerCompose --> mysql

    %% Tests dotted
    ControllerTest -.-> PessoaController
    ServiceTest -.-> PessoaService
    AppTest -.-> ApiPessoaApplication

    %% Click events
    click ApiPessoaApplication "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/ApiPessoaApplication.java"
    click PessoaController "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/controller/PessoaController.java"
    click PessoaService "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/service/PessoaService.java"
    click PessoaRepository "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/repository/PessoaRepository.java"
    click PessoaEntity "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/entity/Pessoa.java"
    click PessoaRequest "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/DTOs/request/PessoaRequest.java"
    click PessoaResponse "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/DTOs/response/PessoaResponse.java"
    click SwaggerConfigNode "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/SwaggerConfig.java"
    click WebConfigNode "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/config/WebConfig.java"
    click CpfJaCadastradoException "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/exception/CpfJaCadastradoException.java"
    click NotFoundException "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/exception/NotFoundException.java"
    click GlobalExceptionHandles "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/java/com/pessoa/apipessoa/exception/GlobalExceptionHandles.java"
    click ApplicationProperties "https://github.com/josealbertonp/api-pessoa/blob/main/src/main/resources/application.properties"
    click InitSQL "https://github.com/josealbertonp/api-pessoa/blob/main/init/init.sql"
    click DockerfileNode "https://github.com/josealbertonp/api-pessoa/tree/main/Dockerfile"
    click DockerCompose "https://github.com/josealbertonp/api-pessoa/blob/main/docker-compose.yml"
    click EnvExample "https://github.com/josealbertonp/api-pessoa/blob/main/.env_example"
    click ControllerTest "https://github.com/josealbertonp/api-pessoa/blob/main/src/test/java/com/pessoa/apipessoa/controller/PessoaControllerTest.java"
    click ServiceTest "https://github.com/josealbertonp/api-pessoa/blob/main/src/test/java/com/pessoa/apipessoa/service/PessoaServiceTest.java"
    click AppTest "https://github.com/josealbertonp/api-pessoa/blob/main/src/test/java/com/pessoa/apipessoa/ApiPessoaApplicationTests.java"

    %% Styles
    classDef external fill:#eef,stroke:#77a,stroke-width:1px
    classDef controller fill:#ccf,stroke:#00f,stroke-width:1px
    classDef service fill:#cfc,stroke:#0a0,stroke-width:1px
    classDef repository fill:#fec,stroke:#fa0,stroke-width:1px
    classDef entity fill:#cff,stroke:#0aa,stroke-width:1px
    classDef dto fill:#ffc,stroke:#aa0,stroke-width:1px
    classDef config fill:#fdf,stroke:#a0a,stroke-width:1px
    classDef exception fill:#fcc,stroke:#f00,stroke-width:1px
    classDef database fill:#ddd,stroke:#888,stroke-width:1px,stroke-dasharray: 2 2
    classDef infra fill:#eee,stroke:#666,stroke-dasharray: 2 2
    classDef test fill:#f9f,stroke:#909,stroke-dasharray: 2 2,stroke-width:1px
```
