# kougianos/rest-api-aggregator architecture

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

- Interactive diagram: https://gitdiagram.com/kougianos/rest-api-aggregator
- Repository: https://github.com/kougianos/rest-api-aggregator

## Overview

##### Main Components
- Client/Consumer: The entry point of requests to the aggregator service.
– Application Entry Point (Application.java) that wires up the Spring Boot application.
– Configuration Layer: Components like AppProperties and WebClientConfig configure the application behavior and the reactive WebClient (with timeouts, etc.).
– Request Router & Handler: Classes like ServiceRouter and ServiceHandler route and process incoming requests and determine what APIs to call.
– Throttling & Batching Mechanism: The queue-related classes (CustomQueue, QueueManager, and QueueScheduler) are the heart of the throttling and batching functionality.
– External API Client: The ExternalApiClient calls out to the external backend service (which hosts the Pricing, Track, and Shipments APIs) asynchronously using Spring WebFlux (reactive programming).
– Aggregation Service: AggregationService is responsible for merging responses and generating the final aggregated response.
– Utility and DTO Components: Supporting classes such as GenericMap and Constants that help with data conversion and maintaining contract consistency.
- External Backend Service: This represents the external system that the aggregator calls (with endpoints for pricing, track, and shipments).

##### Relationships and Data Flow
– Incoming HTTP requests are handled by the request router (ServiceRouter/ServiceHandler).
– The request’s parameters determine which of the External API calls need to be made.
– For each API type (pricing, track, shipments), requests are added to corresponding queues (implemented via CustomQueue).
– A Scheduler (QueueScheduler) runs periodically to check these queues. It “fills” any incomplete queues (using a dummy value mechanism) and releases waiting threads if the queue isn’t full, ensuring that responses are returned within the SLA.
– Once the throttling/batching criteria are met, the ExternalApiClient is triggered to make the outbound asynchronous calls via a reactive WebClient.
– The AggregationService collects and merges the responses into a GenericMap before sending the aggregated response back to the client.
- The ExternalApiClient call is configured with a read timeout (5 seconds), and there is an asynchronous reactive chain (using Mono/Flux) that ties the flow together.

##### Key Architectural Patterns and Design Principles
- Microservice and API Gateway style: Even though this is a single service, its role is to combine multiple external APIs into one façade.
- Reactive Programming: The entire flow employs Spring WebFlux, meaning that requests are handled asynchronously and in a non-blocking fashion.
- Throttling and Batching: Managed by a combination of LinkedBlockingQueue (extended by CustomQueue) and a scheduler. The design pattern here is somewhat of a “buffering” pattern to intercept and batch requests.
- Separation of Concerns: Different packages handle configuration, routing, service logic, and utility functions giving a cleaner separation between the API handling, aggregation logic, and background processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global External Components
    C["Client/Consumer"]:::client
    EB["External Backend Service"]:::external

    %% API Aggregator Service Subgraph
    subgraph "API Aggregator Service"
        A1["Application.java"]:::aggregator

        subgraph "Configuration Layer"
            CP["AppProperties"]:::config
            CW["WebClientConfig"]:::config
        end

        subgraph "Request Routing"
            SR["ServiceRouter"]:::router
            SH["ServiceHandler"]:::router
        end

        subgraph "Throttling & Batching"
            CQ["CustomQueue"]:::queue
            QM["QueueManager"]:::queue
            QS["QueueScheduler"]:::queue
        end

        subgraph "External Calls & Aggregation"
            EA["ExternalApiClient"]:::api
            AS["AggregationService"]:::api
        end

        subgraph "Utility/DTO"
            CT["Constants"]:::utility
            GM["GenericMap"]:::utility
            SU["ServiceUtils"]:::utility
        end
    end

    %% Data Flow Connections
    C -->|"calls"| SR
    SR -->|"routes"| SH
    SH -->|"queuesRequest"| QM
    QM -->|"managesQueue"| CQ
    CQ -->|"triggers"| QS
    QS -->|"schedulesCall"| EA
    EA -->|"invokes"| EB
    EA -->|"sendsData"| AS
    AS -->|"aggregates"| SH
    SH -->|"returnsResponse"| C

    %% Configuration Influences
    A1 -->|"initializes"| CP
    A1 -->|"initializes"| CW
    CP -->|"configures"| QS
    CW -->|"configures"| EA

    %% Click Events
    click A1 "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/Application.java"
    click CP "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/config/AppProperties.java"
    click CW "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/config/WebClientConfig.java"
    click SR "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/router/ServiceRouter.java"
    click SH "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/router/ServiceHandler.java"
    click CQ "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/queue/CustomQueue.java"
    click QM "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/service/QueueManager.java"
    click QS "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/service/QueueScheduler.java"
    click EA "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/service/ExternalApiClient.java"
    click AS "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/service/AggregationService.java"
    click CT "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/dto/Constants.java"
    click GM "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/dto/GenericMap.java"
    click SU "https://github.com/kougianos/rest-api-aggregator/blob/main/src/main/java/com/kougianos/aggregator/util/ServiceUtils.java"

    %% Styles
    classDef client fill:#ffdd57,stroke:#333,stroke-width:2px;
    classDef external fill:#577590,stroke:#fff,stroke-width:2px;
    classDef aggregator fill:#a1d490,stroke:#333,stroke-width:2px;
    classDef config fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef router fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef queue fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef api fill:#43aa8b,stroke:#333,stroke-width:2px;
    classDef utility fill:#f3722c,stroke:#333,stroke-width:2px;
```
