# espirito-santo-arthais/cidadesibge architecture

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

- Interactive diagram: https://gitdiagram.com/espirito-santo-arthais/cidadesibge
- Repository: https://github.com/espirito-santo-arthais/cidadesibge

## Overview

##### Project type and purpose
- This is a standalone, monolithic RESTful API built with Spring Boot (Maven project).
- Purpose: ingest a CSV of Brazilian cities into a database, expose CRUD and analytics endpoints for cities (e.g., list capitals, count per state, distance calculations).

##### File structure
- Top-level: pom.xml, application wrapper (.mvn, mvnw), README, a CSV under planilha/.
- src/main/java/br/com/senior/DesafioSenior: follows a classic layered MVC pattern:
- controller/ – CidadeController, ImportarPlanilha, utility classes
- service/ – CidadeService (business logic)
- repository/ – CidadeRepository (Spring Data JPA)
- model/ – Cidade, Estado entities/enums
- src/main/resources/application.properties configures the database.
- test/ mirrors the main package for unit/integration tests.

##### Extract key architectural points from README
- One endpoint to load CSV into the database.
- Several read‐only endpoints for filtering, aggregation, and geospatial calculations.
- Endpoints for create and delete city.

##### Main components and their interactions
a. External Clients (Postman, browser, another service)
b. Spring MVC Layer (Controllers)
- CidadeController: exposes HTTP endpoints
- ImportarPlanilha: endpoint to trigger CSV load
- Utility classes for parsing & geolocation
c. Service Layer
- CidadeService: orchestrates business rules, delegates to repository
d. Persistence Layer
- CidadeRepository: Spring Data JPA interface
- Database: e.g., H2 for dev or Postgres/MySQL in production
e. External/File System
- CSV file (planilha/CSV_Cidades_Senior.csv) read during import

##### Architectural patterns & design principles
- Layered (Controller → Service → Repository → Database)
- Separation of concerns:
- Controllers handle HTTP & request validation
- Service holds business logic (calculations, filtering)
- Repository abstracts data access
- Use of Spring Boot auto-configuration and dependency injection
- Entities map one-to-one to database tables via JPA annotations

## Diagram (Mermaid)

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

    subgraph "Application Layer"
        App["DesafioSeniorApplication\n(Spring Boot Entry)"]:::app
    end

    subgraph "API Layer (Controllers)"
        IC["ImportarPlanilha\n@RestController"]:::controller
        CC["CidadeController\n@RestController"]:::controller
        Util["Util\nCSV Parser"]:::controller
        LatLong["LatitudeLongitude\nUtil"]:::controller
        EstadoEnum["EstadoEnum"]:::controller
    end

    subgraph "Business Logic Layer (Service)"
        Service["CidadeService\n@Spring Service"]:::service
    end

    subgraph "Domain Model"
        City["Cidade Entity"]:::model
        State["Estado Class"]:::model
    end

    subgraph "Data Access Layer (Repository)"
        Repo["CidadeRepository\nSpring Data JPA"]:::repository
    end

    subgraph "Data Storage & External Resources"
        DB["Database\n(H2/Postgres)"]:::db
        CSV["CSV_Cidades_Senior.csv\n(planilha)"]:::file
        Config["application.properties"]:::config
    end

    subgraph "Tests"
        Test["DesafioSeniorApplicationTests"]:::test
    end

    Clients -->|HTTP Request| App
    App -->|"calls endpoint"| IC
    App -->|"calls endpoint"| CC
    App -->|"loads config"| Config

    IC -->|"POST Import"| Service
    IC -->|"file read"| CSV
    IC -->|"uses util"| Util
    IC -->|"uses util"| LatLong

    CC -->|"CRUD/analytics"| Service
    CC -->|"uses enum"| EstadoEnum

    Service -->|"business logic"| Repo
    Service -->|"processes entities"| City
    Service -->|"processes entities"| State

    Repo -->|"SQL over JDBC"| DB
    Repo -->|"maps entities"| City
    Repo -->|"maps entities"| State

    Test -->|"tests application"| App

    click App "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/DesafioSeniorApplication.java"
    click IC "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/controller/ImportarPlanilha.java"
    click CC "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/controller/CidadeController.java"
    click Util "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/controller/Util.java"
    click LatLong "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/controller/LatitudeLongitude.java"
    click EstadoEnum "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/controller/EstadoEnum.java"
    click Service "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/service/CidadeService.java"
    click Repo "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/repository/CidadeRepository.java"
    click City "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/model/Cidade.java"
    click State "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/java/br/com/senior/DesafioSenior/model/Estado.java"
    click CSV "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/planilha/CSV_Cidades_Senior.csv"
    click Config "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/main/resources/application.properties"
    click Test "https://github.com/espirito-santo-arthais/cidadesibge/blob/master/src/test/java/br/com/senior/DesafioSenior/DesafioSeniorApplicationTests.java"

    classDef client fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef app fill:#E8EAF6,stroke:#1A237E,color:#0D47A1
    classDef controller fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef service fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef repository fill:#DCEDC8,stroke:#33691E,color:#33691E
    classDef model fill:#F3E5F5,stroke:#4A148C,color:#4A148C
    classDef db fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef file fill:#FFF9C4,stroke:#F57F17,color:#F57F17
    classDef config fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef test fill:#F5F5F5,stroke:#424242,color:#212121
```
