# krostar/httpclient architecture

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

- Interactive diagram: https://gitdiagram.com/krostar/httpclient
- Repository: https://github.com/krostar/httpclient

## Overview

##### Main Components
- Core HTTP Request Builder: Represented by files like builder_request.go and builder_response.go. This is where the chainable API methods (e.g., SendJSON, Do, ReceiveJSON, ErrorOnStatus) are defined.
- HTTP Client Executor ("Doer"): Files such as doer.go (and its variants doer_dump_b64.go) implement the underlying mechanics to actually perform the HTTP request.
- Helper/Utility Functions: Files like helper.go, which likely contain functions abstracting common operations used across the package.
- API Object Abstraction: The pattern of creating an API instance (as demonstrated in the README examples) that pre-configures common behaviors (e.g., default error handlers, API URLs).
- Testing Infrastructure: Both unit tests (e.g., *_test.go files in the root and in the “test” folder) and test doubles like the stubs and spys (e.g., doer_stub.go, doer_spy.go) to simulate client behavior.
- Internal Example Package: Found under internal/example, showing how a client might consume this library.
- Configuration & CI/CD: Files within directories like .github and scripts (format, lint) indicate a configured development environment and automation (e.g., using nix).

##### Relationships and Interactions
- The Public API layer (builder_request and builder_response) sits on top and interacts with calling code; it uses the underlying HTTP client executor (“doer”) to dispatch built requests.
- The API Object aggregates default settings (e.g., error handling for specific HTTP status codes) and routes calls to the appropriate builder methods.
- Helper functions are invoked by both the builder components and the doer to keep common logic DRY.
- Test components mimic or stub out these interactions to verify that request construction, response handling, and error management are working as expected.
- CI/CD and configuration files ensure that the code is built and verified in a consistent environment, giving context to development and deployment practices.

##### Architectural Patterns and Design Principles
- Fluent Interface / Builder Pattern: This is central; the chainable API allows constructing HTTP requests with multiple method calls.
- Separation of Concerns: Request building (API layer), execution (doer), and response handling are cleanly separated.
- Dependency Injection: Although not explicitly shown, the README examples mention injecting the HTTP client, which implies testability and separation of which HTTP client instance is used.
- Testing Abstraction: Use of spies, stubs, and matchers to simulate behavior and assert correctness in unit tests.
- Configurable Defaults: Creating an API object with pre-defined behavior shows an emphasis on reducing repetition and centralizing configuration.

##### Incorporate Relevant Technologies & Frameworks
- Language/Platform: Go programming language.
- CI/CD: GitHub Actions (as seen in .github/workflows) and nix for development environment consistency.
- Testing Tools: Built-in Go testing framework and potentially additional linting/formatting tools as indicated by the scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client Code"):::client

    subgraph "httpclient Package"
        subgraph "Public API Components"
            Builder("HTTP Request Builder (builder_request.go, builder_response.go)"):::api
            APIObj("API Object Abstraction (api.go)"):::api
        end
        subgraph "Execution Components"
            Doer("HTTP Client Executor (doer.go, doer_dump_b64.go)"):::exec
            Helper("Helper/Utility Functions (helper.go)"):::exec
        end
    end

    subgraph "Testing Infrastructure"
        Tests("Unit Tests (api_test.go, builder_request_test.go, builder_response_test.go, helper_test.go, doer_dump_b64_test.go)"):::test
        TestDoubles("Test Doubles (test/doer_stub.go, test/doer_spy.go, request_matcher.go, server.go)"):::test
    end

    subgraph "Internal Examples"
        Internal("Internal Example Package (internal/example)"):::internal
    end

    subgraph "Configuration & CI/CD"
        Config("CI/CD & Dev Config (.github/workflows, .github/dependabot.yml, scripts, shell.nix, .envrc)"):::ci
    end

    %% Data Flow Connections
    Client -->|"calls"| Builder
    Builder -->|"invokes"| APIObj
    APIObj -->|"dispatches"| Doer
    Doer -->|"utilizes"| Helper

    %% Testing Connections
    Tests ---|"verifies"| Builder
    Tests ---|"verifies"| APIObj
    TestDoubles ---|"simulates"| Doer

    %% Internal Example Connections
    Internal ---|"demonstrates usage"| Builder
    Internal ---|"demonstrates usage"| APIObj

    %% Configuration Influence
    Config ---|"supports"| Client
    Config ---|"supports"| Builder

    %% Click Events
    click Builder "https://github.com/krostar/httpclient/blob/main/builder_request.go"
    click APIObj "https://github.com/krostar/httpclient/blob/main/api.go"
    click Doer "https://github.com/krostar/httpclient/blob/main/doer.go"
    click Helper "https://github.com/krostar/httpclient/blob/main/helper.go"
    click Tests "https://github.com/krostar/httpclient/blob/main/api_test.go"
    click TestDoubles "https://github.com/krostar/httpclient/blob/main/test/doer_stub.go"
    click Internal "https://github.com/krostar/httpclient/tree/main/internal/example"
    click Config "https://github.com/krostar/httpclient/tree/main/.github/workflows"

    %% Styles
    classDef client fill:#ccf,stroke:#333,stroke-width:2px;
    classDef api fill:#fdd,stroke:#f66,stroke-width:2px;
    classDef exec fill:#dfd,stroke:#393,stroke-width:2px;
    classDef test fill:#ddf,stroke:#66f,stroke-width:2px;
    classDef internal fill:#ffe,stroke:#aa0,stroke-width:2px;
    classDef ci fill:#eee,stroke:#999,stroke-width:2px;
```
