# increase/increase-go architecture

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

- Interactive diagram: https://gitdiagram.com/increase/increase-go
- Repository: https://github.com/increase/increase-go

## Overview

##### Main Components
- Client Component: At the top level, you have the client object (created by calling NewClient in the package main) that acts as the primary entry point for consumers. This component is configured using the functional options pattern (see the “option” package).
- Resources/Endpoints: There are many individual resources represented by Go source files (such as account.go, accounttransfer.go, achtransfer.go, etc.). Each of these modules “models” a resource type in the Increase API.
- Request & Response Handling: Notice the extensive use of methods that wrap the API’s request payloads (“Field” type, JSON responses, etc.). Internally, there are utilities (in the “internal” folder) for API error management (internal/apierror), encoding/decoding JSON (internal/apijson), handling API forms (internal/apiform), and building queries (internal/apiquery).
- Simulation & Testing Components: The simulation files (e.g. simulationaccounttransfer.go, simulationcarddispute.go) and extensive _test.go files imply that the library not only provides standard API client functionality but also support for simulating various operations for testing.
- Utility Libraries: There are libraries like “packages” (e.g., pagination) and “lib” that provide additional helper functions and abstractions.
- External Interfaces: Finally, the API’s interaction itself with the Increase REST API is primary. The client sends HTTP requests and handles responses, optionally through the middleware configured via options.

##### Relationships and Data Flow
- At the highest level, the Consumer Code interacts with the Client. The Client component is configured by the “option” package (functional options) that sets request headers, timeouts, middleware, etc.
- The Client exposes various methods (e.g., Accounts.New, Accounts.List) which internally call specific resource functions defined in separate modules (like account.go, accounttransfer.go).
- These resource functions perform request setup (using the Field helpers and custom types) and then pass control to the lower-level HTTP client.
- Beneath the resource layer, the “internal” packages are used:
- internal/apijson – encodes/decodes API call payloads and manages field tags and marshaling.
- internal/apierror – interprets error responses, wraps the HTTP response/request into a structured error.
- internal/apiquery and apiform – build and format query strings and form data.
- The “simulation” modules show that there is an abstraction layer where one can simulate API responses or perform integration/test operations.
- Important supporting pieces include configuration files (e.g., go.mod, Dockerfiles, CI workflows) which support building, testing, and continuous integration, though they are more on the implementation side than in the runtime architecture.

##### Architectural Patterns & Design Principles
- Modular Design: The project is split into many small, focused components (each resource file, the internal packages, configuration files, and options) ensuring separation of concerns.
- Functional Options Pattern: The configuration and customization of the client and individual requests are handled via closures (“option”) making the configuration highly flexible.
- Typed API Communication: The use of wrapper Field types for request parameters and specific response types (with embedded .JSON metadata) provides safe input/output parameter handling.
- Error Handling & Middleware: The client wraps each HTTP request and response to inject middleware (e.g., logging, retries, custom headers) and error handling components, which is reflected in modules like internal/apierror and the option.WithMiddleware usage.

##### Detailed Recommendations for the Principal Software Engineer
- Under each resource endpoint, annotate the underlying use of utility packages (apijson, apiform, etc.) for request formation and response parsing.
- Network boundary where HTTP requests leave the client and are sent to the Increase API.
- Testing and simulation components in a separate section to emphasize how the library is verified and how simulation endpoints mimic real interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Consumer Code"]:::consumer

    subgraph "Client Interface"
        direction TB
        C["API Client"]:::client
        F["Functional Options"]:::client
    end

    subgraph "Resource Endpoints"
        direction TB
        R1["Account Resource"]:::resource
        R2["AccountTransfer Resource"]:::resource
        R3["ACHTransfer Resource"]:::resource
    end

    subgraph "Internal Utilities"
        direction TB
        J["JSON Handling"]:::internal
        E["API Error Management"]:::internal
        Q["Query Handler"]:::internal
        Fm["Form Handler"]:::internal
    end

    subgraph "Simulation & Testing"
        direction TB
        S["Simulation Components"]:::simulation
    end

    subgraph "Utility Libraries"
        direction TB
        P["Pagination"]:::utility
        L["Additional Helpers"]:::utility
    end

    subgraph "External Service"
        direction TB
        X["Increase REST API"]:::external
    end

    %% Connections between components
    A -->|"initializes"| C
    C -->|"configuredBy"| F
    C -->|"calls"| R1
    C -->|"calls"| R2
    C -->|"calls"| R3

    R1 -->|"uses"| J
    R2 -->|"uses"| J
    R3 -->|"uses"| J

    J -->|"sendsHTTPReq"| X
    X -->|"returnsResponse"| J

    R1 -->|"errorHandling"| E
    R2 -->|"errorHandling"| E
    R3 -->|"errorHandling"| E

    R1 -->|"buildsQuery"| Q
    R2 -->|"buildsQuery"| Q
    R3 -->|"buildsQuery"| Q

    R1 -->|"buildsForm"| Fm
    R2 -->|"buildsForm"| Fm
    R3 -->|"buildsForm"| Fm

    C -->|"usesHelpers"| P
    C -->|"usesHelpers"| L

    S -->|"simulatesCall"| C

    %% Click Events
    click C "https://github.com/increase/increase-go/blob/main/client.go"
    click F "https://github.com/increase/increase-go/blob/main/option/requestoption.go"
    click R1 "https://github.com/increase/increase-go/blob/main/account.go"
    click R2 "https://github.com/increase/increase-go/blob/main/accounttransfer.go"
    click R3 "https://github.com/increase/increase-go/blob/main/achtransfer.go"
    click J "https://github.com/increase/increase-go/tree/main/internal/apijson"
    click E "https://github.com/increase/increase-go/blob/main/internal/apierror/apierror.go"
    click Q "https://github.com/increase/increase-go/tree/main/internal/apiquery"
    click Fm "https://github.com/increase/increase-go/tree/main/internal/apiform"
    click S "https://github.com/increase/increase-go/blob/main/simulation.go"
    click P "https://github.com/increase/increase-go/blob/main/packages/pagination/pagination.go"
    click L "https://github.com/increase/increase-go/tree/main/lib"

    %% Styles
    classDef consumer fill:#d0e1ff,stroke:#000,stroke-width:2px;
    classDef client fill:#abdce0,stroke:#000,stroke-width:2px;
    classDef resource fill:#f7d794,stroke:#000,stroke-width:2px;
    classDef internal fill:#ffddcc,stroke:#000,stroke-width:2px;
    classDef simulation fill:#c2f0c2,stroke:#000,stroke-width:2px;
    classDef utility fill:#d1c4e9,stroke:#000,stroke-width:2px;
    classDef external fill:#ffadad,stroke:#000,stroke-width:2px;
```
