# guinetik/rocketrest architecture

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

- Interactive diagram: https://gitdiagram.com/guinetik/rocketrest
- Repository: https://github.com/guinetik/rocketrest

## Overview

##### Project type and purpose
- This is a Java 8 library (rocketrest-core) for making HTTP API requests via a clean, fluent interface, plus an examples module demonstrating usage.
- It provides synchronous, asynchronous and “fluent” (Result-pattern) APIs, pluggable authentication, JSON serialization, circuit-breaker support, and client decorators.

##### File structure
- Top-level modules:
- rocketrest-core – the core library under src/main/java/com/guinetik/rr
- examples – a Maven project showing how to call RocketRest in user code
- Within rocketrest-core:
- Facade and config: RocketRest, RocketRestConfig, RocketRestOptions
- API clients: AbstractApiClient, DefaultApiClient, AsyncApiClient, FluentApiClient
- HTTP layer: RocketClientFactory → RocketClient (interface) → DefaultHttpClient, AsyncHttpClient, CircuitBreakerClient, MockRocketClient
- Auth strategies: AuthStrategyFactory → BasicAuth, BearerToken, OAuth2*, NoAuth
- JSON: JsonObjectMapper
- Request/response: RequestBuilder, RequestSpec, Result, ApiError
- Utilities: StreamUtils, ResponseLogger
- Build and CI: Maven poms, GitHub workflows, examples POM

##### README for additional insights
- It describes the architecture in terms of a facade (RocketRest) over configurable clients, pluggable authentication, and decorators (circuit-breaker, custom).
- Emphasizes minimal dependencies (Jackson, SLF4J) and compatibility with JDK8.

a. Main components
1) Top-level Facade (RocketRest)
2) Configuration module (RocketRestConfig, Options)
3) Client Factory (RocketClientFactory)
4) API Client implementations (DefaultApiClient, AsyncApiClient, FluentApiClient)
5) HTTP transport layer (DefaultHttpClient → HttpURLConnection, AsyncHttpClient)
6) Decorators (CircuitBreakerClient, custom decorators)
7) Authentication strategies (AuthStrategy variants)
8) JSON serialization (JsonObjectMapper)
9) Request building (RequestBuilder, RequestSpec)
10) Result/Error handling (Result, ApiError)
11) Utilities (ResponseLogger, StreamUtils)
b. Relationships and data flow
- User code calls RocketRest (sync(), async(), fluent() or direct)
- RocketRest delegates to the appropriate ApiClient
- ApiClient uses RequestBuilder to compose HTTP requests
- AuthStrategy injects credentials into requests
- Requests pass to RocketClientFactory → chosen RocketClient
- HTTP client (DefaultHttpClient or AsyncHttpClient) executes via HttpURLConnection
- CircuitBreakerClient wraps the HTTP client if enabled
- Responses flow back through JsonObjectMapper into POJOs or Result objects
- Errors map to ApiError or exceptions
c. Architectural patterns
- Facade (RocketRest)
- Factory (RocketClientFactory)
- Strategy (AuthStrategy)
- Decorator (CircuitBreakerClient, custom decorators)
- Result pattern for error handling
- Asynchronous adapter (CompletableFuture via AsyncApiClient)
d. Key technologies
- Java 8, CompletableFuture
- HttpURLConnection (default transport)
- Jackson (JSON)
- SLF4J (logging)

##### Emphasize
- Be detailed: capture every package-level component.
- Keep RocketRest prominently at the top.
- Extension points (AuthStrategy, decorators) with special borders or callouts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    RocketRest["RocketRest (Facade API)"]:::facade

    subgraph "Configuration"
        Config["RocketRestConfig"]:::core
        Options["RocketRestOptions"]:::core
        SecureConfig["RocketRestSecureConfig"]:::core
    end

    subgraph "API Client Layer"
        AbstractApiClient["AbstractApiClient"]:::core
        DefaultApiClient["DefaultApiClient"]:::core
        AsyncApiClient["AsyncApiClient"]:::core
        FluentApiClient["FluentApiClient"]:::core
    end

    subgraph "HTTP Transport & Decorators"
        Factory["RocketClientFactory"]:::core
        RCInterface["RocketClient (interface)"]:::transport
        DefaultHttpClient["DefaultHttpClient"]:::transport
        AsyncHttpClient["AsyncHttpClient"]:::transport
        CircuitBreakerClient["CircuitBreakerClient"]:::transport
        MockRocketClient["MockRocketClient"]:::transport
    end

    subgraph "Auth Strategies"
        AuthFactory["AuthStrategyFactory"]:::core
        BasicAuthStrategy["BasicAuthStrategy"]:::strategy
        BearerTokenStrategy["BearerTokenStrategy"]:::strategy
        NoAuthStrategy["NoAuthStrategy"]:::strategy
        AbstractOAuth2["AbstractOAuth2Strategy"]:::strategy
        OAuth2AssertionStrategy["OAuth2AssertionStrategy"]:::strategy
        OAuth2ClientCredStrategy["OAuth2ClientCredentialsStrategy"]:::strategy
        OAuth2PasswordStrategy["OAuth2PasswordStrategy"]:::strategy
    end

    subgraph "JSON, Request & Result Utilities"
        JsonObjectMapper["JsonObjectMapper"]:::utils
        RequestBuilder["RequestBuilder"]:::utils
        RequestSpec["RequestSpec"]:::utils
        Result["Result"]:::utils
        ApiError["ApiError"]:::utils
        ResponseLogger["ResponseLogger"]:::utils
        StreamUtils["StreamUtils"]:::utils
    end

    Examples["Examples Module"]:::facade

    Examples -->|"uses"| RocketRest
    RocketRest -->|configures| Config
    RocketRest -->|configures| Options
    RocketRest -->|configures| SecureConfig
    RocketRest -->|delegates to| AbstractApiClient
    RocketRest -->|delegates to| AsyncApiClient
    RocketRest -->|delegates to| FluentApiClient

    AbstractApiClient -->|"builds client"| Factory
    DefaultApiClient -->|"builds client"| Factory
    AsyncApiClient -->|"builds client"| Factory
    FluentApiClient -->|"builds client"| Factory

    Factory -->|creates| RCInterface
    RCInterface -->|"executes"| DefaultHttpClient
    RCInterface -->|"executes"| AsyncHttpClient
    RCInterface -->|"wraps"| CircuitBreakerClient
    RCInterface -->|"mockable"| MockRocketClient

    CircuitBreakerClient -->|"decorates"| DefaultHttpClient
    CircuitBreakerClient -->|"decorates"| AsyncHttpClient

    Factory -->|"selects strategy"| AuthFactory
    AuthFactory -->|"provides"| BasicAuthStrategy
    AuthFactory -->|"provides"| BearerTokenStrategy
    AuthFactory -->|"provides"| NoAuthStrategy
    AuthFactory -->|"provides"| AbstractOAuth2
    AbstractOAuth2 -->|"extends"| OAuth2AssertionStrategy
    AbstractOAuth2 -->|"extends"| OAuth2ClientCredStrategy
    AbstractOAuth2 -->|"extends"| OAuth2PasswordStrategy

    DefaultApiClient -->|uses| RequestBuilder
    AsyncApiClient -->|uses| RequestBuilder
    FluentApiClient -->|uses| RequestBuilder
    RequestBuilder -->|defines| RequestSpec
    RequestBuilder -->|injects auth| AuthFactory

    DefaultHttpClient -->|serializes| JsonObjectMapper
    AsyncHttpClient -->|serializes| JsonObjectMapper
    JsonObjectMapper -->|maps to| Result
    JsonObjectMapper -->|maps errors to| ApiError

    DefaultHttpClient -->|logs| ResponseLogger
    DefaultHttpClient -->|streams| StreamUtils

    classDef facade fill:#BBDEFB,stroke:#000;
    classDef core fill:#C8E6C9,stroke:#000;
    classDef transport fill:#FFE0B2,stroke:#000;
    classDef strategy fill:#FFF9C4,stroke:#000;
    classDef utils fill:#CFD8DC,stroke:#000;

    click RocketRest "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/RocketRest.java"
    click Config "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/RocketRestConfig.java"
    click Options "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/RocketRestOptions.java"
    click SecureConfig "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/RocketRestSecureConfig.java"
    click Factory "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/http/RocketClientFactory.java"
    click AbstractApiClient "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/api/AbstractApiClient.java"
    click DefaultApiClient "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/api/DefaultApiClient.java"
    click AsyncApiClient "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/api/AsyncApiClient.java"
    click FluentApiClient "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/api/FluentApiClient.java"
    click RCInterface "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/http/RocketClient.java"
    click DefaultHttpClient "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/http/DefaultHttpClient.java"
    click AsyncHttpClient "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/http/AsyncHttpClient.java"
    click CircuitBreakerClient "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/http/CircuitBreakerClient.java"
    click MockRocketClient "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/http/MockRocketClient.java"
    click AuthFactory "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/auth/AuthStrategyFactory.java"
    click BasicAuthStrategy "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/auth/BasicAuthStrategy.java"
    click BearerTokenStrategy "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/auth/BearerTokenStrategy.java"
    click NoAuthStrategy "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/auth/NoAuthStrategy.java"
    click AbstractOAuth2 "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/auth/AbstractOAuth2Strategy.java"
    click OAuth2AssertionStrategy "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/auth/OAuth2AssertionStrategy.java"
    click OAuth2ClientCredStrategy "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/auth/OAuth2ClientCredentialsStrategy.java"
    click OAuth2PasswordStrategy "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/auth/OAuth2PasswordStrategy.java"
    click JsonObjectMapper "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/json/JsonObjectMapper.java"
    click RequestBuilder "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/request/RequestBuilder.java"
    click RequestSpec "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/request/RequestSpec.java"
    click Result "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/result/Result.java"
    click ApiError "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/result/ApiError.java"
    click ResponseLogger "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/util/ResponseLogger.java"
    click StreamUtils "https://github.com/guinetik/rocketrest/blob/master/rocketrest-core/src/main/java/com/guinetik/rr/util/StreamUtils.java"
    click Examples "https://github.com/guinetik/rocketrest/tree/master/examples/src/main/java/com/guinetik/examples/"
```
