# hamvocke/spring-testing architecture

> Architecture diagram of the GitHub repository hamvocke/spring-testing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamvocke/spring-testing
- Repository: https://github.com/hamvocke/spring-testing

## Overview

##### Project type and purpose
- This is a Spring Boot–based microservice whose primary purpose is to expose a small REST API (“hello” and “weather” endpoints), persist `Person` entities in a database, and demonstrate a comprehensive test suite arranged according to the Test Pyramid. It is not a full multi-module monolith or a frontend/backend web app with UI—it’s a single back-end service with an external HTTP dependency (the OpenWeatherMap API) and an in-memory/PostgreSQL data store.

##### File structure
- Top-level build and CI: `build.gradle`, `gradlew`, `.circleci/config.yml`, `Dockerfile`, `startDatabase.sh`
- Main code under `src/main/java/example`:
- `ExampleApplication.java` – Spring Boot entry point
- `ExampleController.java` – REST controller defining `/hello` and `/weather` endpoints
- `person/Person.java`, `person/PersonRepository.java` – JPA entity and repository
- `weather/WeatherClient.java`, `weather/WeatherResponse.java` – HTTP client & DTO for external API
- Config: `src/main/resources/application.properties`, env files (`.envrc`, `env.sample`) for `WEATHER_API_KEY` and database
- Tests under `src/test/java/example`: unit tests, integration tests (DB, HTTP stubs), end-to-end tests (Selenium, RestAssured), consumer-driven contracts (Pact), and test helpers
- Docker and database startup script to spin up PostgreSQL on 15432

##### Key insights from the README
- The architecture is a classic 3-tier layered service:
1. Web/API layer (Controller)
2. Service/Data layer (Repository → Database)
3. Integration layer (HTTP Client → External Weather API)
- It demonstrates all levels of the test pyramid: Unit → Integration → End-to-End → Acceptance (Pact), using JUnit, Mockito, MockMvc, RestAssured, WireMock, Pact.
- The service runs on port 8080, connects to Postgres and OpenWeatherMap via JSON/HTTP.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Context
    APIConsumer["API Consumer\n(cURL, UI, API Gateway)"]:::external
    APIConsumer -->|HTTP/JSON| Controller

    %% Spring Boot Service Container
    subgraph "Spring Boot Service" 
        direction TB
        ExampleApp["ExampleApplication"]:::internal
        ExampleController["ExampleController\n(hello, weather endpoints)"]:::internal
        PersonRepo["PersonRepository"]:::internal
        WeatherClient["WeatherClient"]:::internal
        WeatherResponse["WeatherResponse"]:::internal
        ApplicationProps["application.properties"]:::infra

        ExampleApp --> ExampleController
        ExampleController --> PersonRepo
        ExampleController --> WeatherClient
        WeatherClient --> WeatherResponse
    end

    %% Infrastructure
    PersonRepo -->|JPA CRUD| Database
    WeatherClient -->|HTTP/JSON| ExternalAPI
    startDb["startDatabase.sh"]:::infra
    DockerfileNode["Dockerfile"]:::infra
    CIConfig[".circleci/config.yml"]:::infra

    %% External Systems
    Database["PostgreSQL\n(port 15432)"]:::db
    ExternalAPI["OpenWeatherMap API"]:::external

    %% Testing Pyramid
    subgraph "Testing Layers"
        direction TB
        UnitTests["Unit Tests\n(Controller, WeatherClient, DTO)"]:::test
        IntegrationTests["Integration Tests\n(Repo, HTTP stub)"]:::test
        APILevelTests["API-Level Tests\n(MockMvc)"]:::test
        E2ETests["End-to-End Tests\n(RestAssured, Selenium)"]:::test
        PactTests["Consumer-Driven Contract Tests\n(Pact)"]:::test

        UnitTests --> IntegrationTests
        IntegrationTests --> APILevelTests
        APILevelTests --> E2ETests
        E2ETests --> PactTests
    end

    %% Relationships
    Controller -->|uses| APILevelTests
    Database -->|stubbed by| IntegrationTests
    ExternalAPI -->|stubbed by| PactTests

    %% Click Events
    click ExampleApp "https://github.com/hamvocke/spring-testing/blob/main/src/main/java/example/ExampleApplication.java"
    click ExampleController "https://github.com/hamvocke/spring-testing/blob/main/src/main/java/example/ExampleController.java"
    click PersonRepo "https://github.com/hamvocke/spring-testing/blob/main/src/main/java/example/person/PersonRepository.java"
    click WeatherClient "https://github.com/hamvocke/spring-testing/blob/main/src/main/java/example/weather/WeatherClient.java"
    click WeatherResponse "https://github.com/hamvocke/spring-testing/blob/main/src/main/java/example/weather/WeatherResponse.java"
    click ApplicationProps "https://github.com/hamvocke/spring-testing/blob/main/src/main/resources/application.properties"
    click startDb "https://github.com/hamvocke/spring-testing/blob/main/startDatabase.sh"
    click DockerfileNode "https://github.com/hamvocke/spring-testing/tree/main/Dockerfile"
    click CIConfig "https://github.com/hamvocke/spring-testing/blob/main/.circleci/config.yml"
    click UnitTests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/ExampleControllerTest.java"
    click UnitTests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/weather/WeatherClientTest.java"
    click UnitTests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/weather/WeatherResponseTest.java"
    click IntegrationTests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/person/PersonRepositoryIntegrationTest.java"
    click IntegrationTests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/weather/WeatherClientIntegrationTest.java"
    click APILevelTests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/ExampleControllerAPITest.java"
    click E2ETests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/HelloE2ERestTest.java"
    click E2ETests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/HelloE2ESeleniumTest.java"
    click PactTests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/weather/WeatherClientConsumerTest.java"
    click PactTests "https://github.com/hamvocke/spring-testing/blob/main/src/test/java/example/ExampleProviderTest.java"
    click PactTests "https://github.com/hamvocke/spring-testing/blob/main/target/pacts/person_consumer-person_provider.json"
    click PactTests "https://github.com/hamvocke/spring-testing/blob/main/target/pacts/sample_microservice-weather_provider.json"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef test fill:#D3D3D3,stroke:#333,stroke-width:1px
```
