# plaid/plaid-go architecture

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

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

## Overview

##### Main Components
- Configuration Module – Responsible for initializing the API client with Plaid credentials, setting headers, and choosing the environment (Sandbox, Production, etc.). This module encapsulates user-defined options and environmental settings.
- API Client (Facade) – Acts as the main entry point for the library users. It exposes high-level methods that correspond to different Plaid API endpoints (e.g., AccountsBalanceGet, TransactionsGet, SandboxPublicTokenCreate, etc.). It leverages the configuration settings and orchestrates HTTP request/response handling.
- Endpoint Layer / HTTP Abstraction – Represents the set of methods that construct the request models, serialize input, and execute the HTTP calls. Each endpoint is paired with a request and response model.
- Models / Data Structures – A large collection of generated model files (all the model_*.go files) that represent both request data and response payloads. This layer provides the schema for each API’s input and output.
- Error Handling Module – Includes helper types and functions (such as converting generic API errors into Plaid-specific errors) to standardize error handling.
- OpenAPI Code Generator & Template Layer – The “templates” directory holds Mustache templates used in generating much of the code in the “plaid” package. This illustrates that much of the client library is auto-generated using the OpenAPI specification found in the “api” directory.
- Testing & Validation – The “tests” directory contains robust unit and integration tests which validate the behavior of the client logic, endpoints, and error processing.

##### Relationships and Interactions
- The library’s public API (exposed through the API Client) receives client configuration data (credentials, environment, headers) and instantiates a configured client object.
- When a client calls an API method (e.g., to exchange a public token for an access token), the API Client constructs a request model (from the Models layer) and hands it off to the HTTP abstraction/endpoint layer.
- The HTTP abstraction (often as methods on sub-components within the client) processes the API call by building an HTTP request, invoking the remote Plaid API, and then serializing the JSON response into the corresponding model.
- Errors that arise are funnelled through the error handling module which packages them into a standardized PlaidError type.
- The generation of these models and methods is driven by the OpenAPI code generator, which uses templates and the API spec (*.yaml file) as inputs.
- The test suite simulates client interactions and validates that the different layers correctly process requests, handle errors, and produce the expected responses.

##### Architectural Patterns & Design Principles
- Separation of Concerns – The design clearly segments responsibilities: configuration, API call management, data modelling, error handling, and testing are well isolated.
- Facade Pattern – The API Client serves as a façade that simplifies interactions, hiding the underlying complexity of HTTP calls and error management.
- Code Generation – A significant portion of the library is auto-generated from an OpenAPI specification using Mustache templates, ensuring consistency between the API schema and client implementation.
- Dependency Injection – The configuration object is passed into the client creation, allowing for flexible environment setup and overriding defaults (e.g., headers or environment).

##### Elements
- The Configuration module feeds parameters into the API Client.
- The API Client invokes endpoint methods that in turn use Models for serialization/deserialization.
- The HTTP abstraction communicates with the remote Plaid API and returns responses or errors to the API Client.
- Errors flow into the Error Handling module and propagate back to the caller.
- The Test Suite verifies interactions among these layers.
- Given that this is a client library rather than a full-stack application, emphasize the inner workings of the library and its transformation of API interactions rather than showing separate frontend/backend servers.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Configuration & Environment Setup"]:::config
    B["API Client (Facade)"]:::client
    C["HTTP Abstraction / Endpoint Layer"]:::endpoint
    D["Models / Data Structures"]:::models
    E["Error Handling Module"]:::error
    F["OpenAPI Template Generator"]:::codegen
    G["Testing & Validation"]:::testing
    H["Plaid API (External)"]:::external

    A -->|"initializes"| B
    B -->|"invokes"| C
    B -->|"builds_request_with"| D
    C -->|"serializes_deserializes"| D
    C -->|"on_error_triggers"| E
    E -->|"returns_error_to"| B
    C -->|"HTTP_call"| H
    H -->|"response"| C
    F -->|"generates_code_for"| D
    F -->|"generates_code_for"| C
    G -->|"validates"| B
    G -->|"validates"| C
    G -->|"validates"| E

    click A "https://github.com/plaid/plaid-go/blob/master/plaid/configuration.go"
    click B "https://github.com/plaid/plaid-go/blob/master/plaid/client.go"
    click C "https://github.com/plaid/plaid-go/blob/master/plaid/api_plaid.go"
    click D "https://github.com/plaid/plaid-go/blob/master/plaid/model_account_balance.go"
    click E "https://github.com/plaid/plaid-go/blob/master/plaid/utils.go"
    click F "https://github.com/plaid/plaid-go/tree/master/templates/go"
    click G "https://github.com/plaid/plaid-go/tree/master/tests"

    classDef config fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
    classDef client fill:#c9daf8,stroke:#1155cc,stroke-width:2px;
    classDef endpoint fill:#d9ead3,stroke:#274e13,stroke-width:2px;
    classDef models fill:#fff2cc,stroke:#b38600,stroke-width:2px;
    classDef error fill:#f9cb9c,stroke:#e69138,stroke-width:2px;
    classDef codegen fill:#ead1dc,stroke:#990066,stroke-width:2px;
    classDef testing fill:#d0e0e3,stroke:#11505c,stroke-width:2px;
    classDef external fill:#ffe599,stroke:#b45f06,stroke-width:2px,stroke-dasharray: 5,5;
```
