How harveyfullstack/kotlin-weather-app works
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.