# gojek/heimdall architecture

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

- Interactive diagram: https://gitdiagram.com/gojek/heimdall
- Repository: https://github.com/gojek/heimdall

## Overview

##### Main Components
- Core HTTP Client: Represent the base HTTP client (e.g., client.go in the root and in the httpclient package) that exposes a fluent interface for making requests.
- Retry & Backoff Mechanism: Include elements for “Backoff” (backoff.go and its test files) and “Retry” (retry.go and its test files) which handle the logic for retrying failed requests with configurable strategies (e.g., constant, exponential, or custom backoff).
- Plugin System: Highlight the extensibility provided by the plugin interface (plugin.go and plugins directory). This includes hooks (OnRequestStart, OnRequestEnd, and OnError) that allow additional behaviors such as logging (e.g., the request_logger plugin).
- Custom HTTP Client Integration: Indicate that Heimdall allows custom HTTP client implementations by accepting a Doer (interface similar to net/http.Client) and wrapping them with added functionality (as described in the README).

##### Architectural Patterns and Design Principles
- Façade pattern: Heimdall provides a simple interface (fluent methods like client.Get() and client.Do()) while hiding the complexity of retries, circuit breaking, etc.
- Layering/Separation of Concerns: Separate components like retry logic, circuit breaker logic, and plugin management are modular. This modularity should be shown by drawing distinct layers and clearly marking inter-component communication.
- Extensibility: Show how plugins attach to the core client to extend functionality without modifying the base logic.

##### Technologies and Frameworks
- Go (Golang) as the primary language.
- References to standard HTTP functionalities (net/http) that are being wrapped by Heimdall.

##### What
- Start at “Client Construction” where options such as timeouts, retry counts, and custom functionalities are set.
- Branch off from this core process into “Retry Logic” and “Circuit Breaker” components if errors occur.
- Clearly differentiate between the base HTTP functionality and the additional safety/resiliency layers.

##### Final Assembly
- Conclude the flow with the outgoing request to the external HTTP endpoint.
- Annotations to highlight the use cases mentioned in the README, such as handling high volume requests, supporting retries, and implementing circuit breaking.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client_Construction["Client Construction"]:::client
    HTTP_Client["HTTP Client"]:::core
    Backoff["Backoff Strategy"]:::resiliency
    Retry["Retry Logic"]:::resiliency
    Circuit["Circuit Breaker (Hystrix)"]:::resiliency
    Plugin["Plugin Manager"]:::extensibility
    External["External HTTP Endpoint"]:::external

    Client_Construction -->|"configures"| HTTP_Client
    HTTP_Client -->|"invokes"| Backoff
    Backoff -->|"triggers"| Retry
    HTTP_Client -->|"wrappedBy"| Circuit
    HTTP_Client -->|"pluginHooks"| Plugin
    HTTP_Client -->|"sends"| External
    Retry -->|"executes"| External
    Circuit -->|"executes"| External

    %% Click Events for Core HTTP Client
    click HTTP_Client "https://github.com/gojek/heimdall/blob/master/client.go"
    click HTTP_Client "https://github.com/gojek/heimdall/blob/master/httpclient/client.go"

    %% Click Events for Retry & Backoff Mechanism - Backoff
    click Backoff "https://github.com/gojek/heimdall/blob/master/backoff.go"
    click Backoff "https://github.com/gojek/heimdall/blob/master/backoff_test.go"

    %% Click Events for Retry & Backoff Mechanism - Retry
    click Retry "https://github.com/gojek/heimdall/blob/master/retry.go"
    click Retry "https://github.com/gojek/heimdall/blob/master/retry_test.go"

    %% Click Events for Circuit Breaker (Hystrix)
    click Circuit "https://github.com/gojek/heimdall/blob/master/hystrix/hystrix_client.go"
    click Circuit "https://github.com/gojek/heimdall/blob/master/hystrix/hystrix_client_test.go"
    click Circuit "https://github.com/gojek/heimdall/blob/master/hystrix/options.go"
    click Circuit "https://github.com/gojek/heimdall/blob/master/hystrix/options_test.go"

    %% Click Events for Plugin System
    click Plugin "https://github.com/gojek/heimdall/blob/master/plugin.go"
    click Plugin "https://github.com/gojek/heimdall/blob/master/plugins/request_logger.go"
    click Plugin "https://github.com/gojek/heimdall/blob/master/httpclient/plugin_mock.go"

    classDef client fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef core fill:#C6E2FF,stroke:#5F9EA0,stroke-width:2px;
    classDef resiliency fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef extensibility fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#A9A9A9,stroke-width:2px;
```
