# cloudflare/cloudflare-go architecture

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

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

## Overview

##### Main Components
a. **Client Layer**
- `client.go` – the entry point (`NewClient`) that produces a `Client` instance.
- `option` package – implements functional options (`RequestOption`) to mutate `RequestConfig`.
b. **Public API Packages** (one per API area)
- Examples: `zones`, `firewall`, `dns`, `accounts`, etc.
- Each package exports CRUD-style methods (e.g. `Zones.New`, `Firewall.List`) and parameter/result structs.
c. **Internal Utilities**
- `internal/apierror` – error wrapping & inspection.
- `internal/apijson`, `internal/apiquery`, `internal/apiform` – encoding/decoding logic for JSON, query strings, multipart forms.
- `internal/requestconfig` – centralizes request configuration.
d. **HTTP Transport**
- The standard library `http.Client` (replaceable via `option.WithHTTPClient`).
e. **External Cloudflare REST API**
- The remote service your SDK talks to over HTTPS.

##### Relationships & Data Flows
- **Developer Code** calls `cloudflare.NewClient(...)`, passing zero or more `option.With…()` helpers.
- Client instance is held by user code; when user invokes e.g. `client.Zones.New(ctx, params, opts…)`:
– Public package (`zones`) calls into **Client Layer**
– Client constructs a `RequestConfig` (URL path, headers, body) using **functional options**
– Client calls into **Internal Utilities** to encode JSON/query/form data
– Client invokes the **HTTP Transport** (e.g. `http.Client.Do(req)`)
– **External API** processes request, returns JSON
– Client uses **Internal Utilities** to decode the JSON into Go structs
– Result is returned to **Developer Code**
- **Dependency Direction**:
Public API Packages → Core Client → Internal Utilities → HTTP Transport → External API.

##### Architectural Patterns & Principles
- **Layering** – clear separation:
1) Public API layer (package-per-API)
2) Core client + options layer
3) Encoding/decoding utilities (internal)
4) HTTP transport
5) External service
- **Functional Options** pattern for request customization.
- **Package-per-API-group** modularization for discoverability and maintainability.
- **Go idioms** – value types for response fields, zero-value semantics, context-aware calls.

##### Capturing Essential Elements
- Be very detailed about the **data-flow path** – from user code, through option mutation, to HTTP call, through JSON decode, back to user.
- Don’t omit the **internal** packages – they are the heart of encoding/decoding and error handling.
- Where **middlewares**, **retries**, and **timeouts** plug in (in the client/options layer).
- **functional options** branching – options applied at client creation vs. per-request.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Application
    Dev["Developer Application"]:::external

    %% Public API Packages
    subgraph "Public API Packages" 
        direction TB
        Zones["zones package"]:::public
        Firewall["firewall package"]:::public
        DNS["dns package"]:::public
        Accounts["accounts package"]:::public
    end

    %% Client & Options Layer
    subgraph "Core Client & Options" 
        direction TB
        Client["client.go / NewClient"]:::core
        Option["option/requestoption.go (WithHTTPClient, WithMiddleware)"]:::core
    end

    %% Internal Utilities
    subgraph "Internal Utilities" 
        direction TB
        APIError["internal/apierror/apierror.go"]:::utils
        APIJSONEnc["internal/apijson/encoder.go"]:::utils
        APIJSONDec["internal/apijson/decoder.go"]:::utils
        APIQueryEnc["internal/apiquery/encoder.go"]:::utils
        APIQueryQuery["internal/apiquery/query.go"]:::utils
        APIFormEnc["internal/apiform/encoder.go"]:::utils
        APIFormForm["internal/apiform/form.go"]:::utils
        RequestConfig["internal/requestconfig/requestconfig.go"]:::utils
        VersionMeta["internal/version.go"]:::utils
    end

    %% HTTP Transport
    HTTPClient["HTTP Transport (http.Client)"]:::transport

    %% External Service
    CloudflareAPI["Cloudflare REST API"]:::externalService

    %% Data Flow
    Dev -->|"calls NewClient"| Client
    Dev -->|"invokes methods"| Zones
    Dev --> Zones
    Dev --> Firewall
    Dev --> DNS
    Dev --> Accounts

    Zones -->|"uses Client instance"| Client
    Firewall --> Client
    DNS --> Client
    Accounts --> Client

    Client -->|"applies functional options"| Option
    Client -->|"builds RequestConfig"| RequestConfig
    Client -->|"encodes via utils"| APIJSONEnc
    Client --> APIQueryEnc
    Client --> APIFormEnc

    APIJSONEnc --> APIError
    APIJSONDec --> APIError
    APIQueryEnc --> APIError
    APIFormEnc --> APIError

    Client --> HTTPClient
    HTTPClient --> CloudflareAPI
    CloudflareAPI --> HTTPClient
    HTTPClient --> APIJSONDec
    APIJSONDec --> Client
    Client --> Dev

    %% Click Events
    click Client "https://github.com/cloudflare/cloudflare-go/blob/main/client.go"
    click Option "https://github.com/cloudflare/cloudflare-go/blob/main/option/requestoption.go"
    click Zones "https://github.com/cloudflare/cloudflare-go/tree/main/zones/"
    click Firewall "https://github.com/cloudflare/cloudflare-go/tree/main/firewall/"
    click DNS "https://github.com/cloudflare/cloudflare-go/tree/main/dns/"
    click Accounts "https://github.com/cloudflare/cloudflare-go/tree/main/accounts/"
    click APIError "https://github.com/cloudflare/cloudflare-go/blob/main/internal/apierror/apierror.go"
    click APIJSONEnc "https://github.com/cloudflare/cloudflare-go/blob/main/internal/apijson/encoder.go"
    click APIJSONDec "https://github.com/cloudflare/cloudflare-go/blob/main/internal/apijson/decoder.go"
    click APIQueryEnc "https://github.com/cloudflare/cloudflare-go/blob/main/internal/apiquery/encoder.go"
    click APIQueryQuery "https://github.com/cloudflare/cloudflare-go/blob/main/internal/apiquery/query.go"
    click APIFormEnc "https://github.com/cloudflare/cloudflare-go/blob/main/internal/apiform/encoder.go"
    click APIFormForm "https://github.com/cloudflare/cloudflare-go/blob/main/internal/apiform/form.go"
    click RequestConfig "https://github.com/cloudflare/cloudflare-go/blob/main/internal/requestconfig/requestconfig.go"
    click VersionMeta "https://github.com/cloudflare/cloudflare-go/blob/main/internal/version.go"

    %% Styles
    classDef public fill:#cce5ff,stroke:#0066cc,color:#003366;
    classDef core fill:#d4edda,stroke:#28a745,color:#155724;
    classDef utils fill:#fff3cd,stroke:#ffc107,color:#856404;
    classDef transport fill:#e2e3e5,stroke:#6c757d,color:#343a40;
    classDef externalService fill:#f8d7da,stroke:#dc3545,color:#721c24;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#343a40;
```
