# harveyfullstack/kotlin-weather-app architecture

> Architecture diagram of the GitHub repository harveyfullstack/kotlin-weather-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harveyfullstack/kotlin-weather-app
- Repository: https://github.com/harveyfullstack/kotlin-weather-app

## Overview

##### Project Type and Purpose
- This is a backend microservice—a Kotlin Spring Boot WebFlux application—that exposes a single reactive REST endpoint (/weather). It fetches data from the external weather.gov API, transforms it (day name, Celsius high, forecast text) using Mono/Flux, and returns a simplified JSON.

##### File Structure
- Top‑level build files: Gradle wrapper, build.gradle.kts, .gitignore.
- src/main/kotlin/com/example/weatherapp:
- WeatherAppApplication.kt: Spring Boot entry point.
- config/WebClientConfig.kt: Defines the reactive WebClient bean.
- controller/WeatherController.kt: Handles incoming HTTP GET /weather.
- service/WeatherService.kt: Orchestrates the call to the external API, applies transformations.
- model/api/WeatherApiResponse.kt: Data classes modeling the raw JSON from weather.gov.
- model/response/WeatherResponse.kt: Data classes for the returned JSON.
- util/TemperatureConverter.kt: Converts Fahrenheit to Celsius.
- exception/WeatherExceptions.kt: Custom exceptions used in reactive error handling.
- listener/StartupInfoLogger.kt: Logs application info on startup.
- src/main/resources/application.properties: Externalized configuration (base URL, path, etc.)
- Tests mirror the structure: unit tests for util/service, controller tests with WebTestClient, integration tests with MockWebServer.

##### Architecture from README
- Clearly layered: Controller → Service → Integration (WebClient) → External API
- Reactive stack: Mono/Flux throughout, non-blocking I/O
- Error handling in reactive chains
- No persistence layer (no database)

a. Main Components
- Client (Browser or HTTP client)
- WeatherController (Spring WebFlux Router/Endpoint)
- WeatherService (Business logic & reactive transformations)
- TemperatureConverter (Utility)
- WebClient (configured in WebClientConfig)
- External Weather.gov API
- Exception Handlers (reactive error pipeline)
- StartupInfoLogger (optional side‑component)
- Configuration Store (application.properties)

b. Relationships & Interactions
1. Client → HTTP GET /weather → WeatherController
2. WeatherController invokes → WeatherService.fetchWeather()
3. WeatherService uses WebClient → calls external API endpoint
4. External API responds → mapped into WeatherApiResponse
5. Service applies → TemperatureConverter & mapping into WeatherResponse
6. Flux/Mono error hooks → WeatherExceptions
7. WeatherResponse emitted back through Controller → Client

c. Architectural Patterns
- Layered (Controller → Service → Integration)
- Reactive Pipeline (Mono/Flux compositions, non‑blocking)
- Externalized Configuration (WebClient base URL, timeouts in application.properties)
- Centralized Logging (StartupInfoLogger logs on application startup)
- Exception Handling in the reactive chain (onErrorMap, doOnError)

d. Key Technologies
- Kotlin, Spring Boot 3.2.8
- Spring WebFlux (Mono, Flux)
- Reactor Netty WebClient
- Gradle Kotlin DSL
- JUnit 5, MockWebServer for tests

##### Elements
- Presentation (e.g., blue)
- Business (e.g., green)
- Integration/External (e.g., orange)
- Configuration/Logging (e.g., gray)
- Rectangles for in‑process components

– Call to WebClient (from WebClientConfig) → External API
– Mapping stages: WeatherApiResponse → TemperatureConverter → WeatherResponse
– Error handling node (onErrorMap → WeatherExceptions)
6. “application.properties” feeding into WebClientConfig.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global Entities
    Client["HTTP Client"]:::external
    Startup["StartupInfoLogger"]:::config

    %% Presentation Layer
    subgraph "Presentation Layer"
        Controller["WeatherController\n(GET /weather)"]:::presentation
    end

    %% Business Layer
    subgraph "Business Layer"
        Service["WeatherService"]:::business
        Converter["TemperatureConverter"]:::business
        ResponseModel["WeatherResponse\n(model)"]:::business
        ExceptionHandler["WeatherExceptions"]:::business
    end

    %% Integration Layer
    subgraph "Integration Layer"
        WebClientBean["WebClient Bean"]:::integration
        ApiModel["WeatherApiResponse\n(model)"]:::integration
    end

    %% External & Config
    subgraph "External & Config"
        ExternalAPI["External weather.gov API"]:::external
        Config["application.properties"]:::config
    end

    %% Connections
    Client -->|"GET /weather"| Controller
    Controller -->|"Mono<WeatherResponse>"| Service
    Service -->|"Flux/Mono stream"| WebClientBean
    WebClientBean -->|"HTTP GET"| ExternalAPI
    ExternalAPI -->|"Raw JSON"| ApiModel
    ApiModel -->|"map & convert"| Converter
    Converter -->|"WeatherResponse"| ResponseModel
    ResponseModel -->|"Mono<WeatherResponse>"| Service
    Service -->|"Mono<WeatherResponse>"| Controller
    Controller -->|"JSON Response"| Client

    Config --> WebClientBean
    Startup --> Config

    %% Click Events
    click Controller "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/kotlin/com/example/weatherapp/controller/WeatherController.kt"
    click Service "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/kotlin/com/example/weatherapp/service/WeatherService.kt"
    click WebClientBean "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/kotlin/com/example/weatherapp/config/WebClientConfig.kt"
    click Converter "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/kotlin/com/example/weatherapp/util/TemperatureConverter.kt"
    click ApiModel "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/kotlin/com/example/weatherapp/model/api/WeatherApiResponse.kt"
    click ResponseModel "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/kotlin/com/example/weatherapp/model/response/WeatherResponse.kt"
    click ExceptionHandler "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/kotlin/com/example/weatherapp/exception/WeatherExceptions.kt"
    click Startup "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/kotlin/com/example/weatherapp/listener/StartupInfoLogger.kt"
    click Config "https://github.com/harveyfullstack/kotlin-weather-app/blob/main/src/main/resources/application.properties"

    %% Styles
    classDef presentation fill:#D6E9F8,stroke:#2B7CE9,color:#0B3D91;
    classDef business fill:#E2F0D9,stroke:#4F8A10,color:#2B5D00;
    classDef integration fill:#FCE5CD,stroke:#C47000,color:#8C4D00;
    classDef config fill:#F2F2F2,stroke:#888888,color:#555555;
    classDef external fill:#F4CCCC,stroke:#CC0000,color:#660000;
```
