# lerianstudio/midaz-sdk-golang architecture

> Architecture diagram of the GitHub repository lerianstudio/midaz-sdk-golang, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lerianstudio/midaz-sdk-golang
- Repository: https://github.com/lerianstudio/midaz-sdk-golang

## Overview

Midaz Go SDK is a typed client for the ledger’s `/v1` and `/v2` APIs. The principal workflow is application code constructing a client, choosing a versioned service facade, and making typed requests that return decoded results or structured errors. Other documented capabilities include OAuth or anonymous authentication, pagination, retries, idempotency, observability, transaction batching, generators, and validation. The graph follows README-described wiring and excerpted calls; several implementation links remain absent because the client constructor and many runtime modules were not sampled.

Main entry points: [`entities/operation_routes_facade.go`](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/operation_routes_facade.go) (Operation routes), [`entities/transaction_routes_facade.go`](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/transaction_routes_facade.go) (Transaction routes), [`models/model.go`](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/models/model.go) (Typed models), [`midaz_options.go`](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/midaz_options.go) (Client options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and services"]
  node_client["Client construction<br/>[midaz.go]"]
  node_options["Client options<br/>[midaz_options.go]"]
  node_v1["V1 services"]
  node_v2["V2 services"]
  node_routeops["Operation routes"]
  node_routetx["Transaction routes"]
  node_models["Typed models<br/>[model.go]"]
  node_pagination["List pagination<br/>[iter.go]"]
end

subgraph group_transport["Transport and resilience"]
  node_http["HTTP response layer<br/>[http.go]"]
  node_auth["Access Manager auth<br/>[access_manager.go]"]
  node_retry["HTTP retries<br/>[http.go]"]
  node_errors["Structured errors<br/>[errors.go]"]
end

subgraph group_domain["Ledger workflows"]
  node_generator["Route generators"]
  node_txbatch["Transaction batches<br/>[batch.go]"]
  node_accounts["Account helpers<br/>[accounts.go]"]
  node_validation["Enhanced validation<br/>[enhanced.go]"]
  node_integrity["Ledger integrity<br/>[checker.go]"]
  node_format["Value formatting<br/>[format.go]"]
end

subgraph group_crosscut["Shared capabilities"]
  node_concurrent["HTTP batching<br/>[http_batch.go]"]
  node_performance["Performance batching<br/>[batch.go]"]
  node_observability["OpenTelemetry<br/>[observability.go]"]
  node_sdkctx["Request context<br/>[sdkctx.go]"]
end

node_app(("SDK consumer"))
node_ledgerapi["Midaz ledger API"]

node_app -->|"constructs"| node_client
node_client -->|"accepts options"| node_options
node_app -->|"uses"| node_v1
node_app -->|"uses"| node_v2
node_v1 -->|"requests &#96;/v1&#96;"| node_ledgerapi
node_v2 -->|"requests &#96;/v2&#96;"| node_ledgerapi
node_routeops -->|"calls endpoints"| node_ledgerapi
node_routetx -->|"calls endpoints"| node_ledgerapi
node_routeops -->|"uses typed inputs"| node_models
node_routetx -->|"uses typed inputs"| node_models
node_v1 -.->|"exposes service"| node_routeops
node_v2 -.->|"exposes service"| node_routeops
node_v1 -.->|"exposes service"| node_routetx
node_v2 -.->|"exposes service"| node_routetx
node_routeops -->|"decodes responses"| node_http
node_routetx -->|"decodes responses"| node_http
node_http -.->|"reports failures"| node_errors
node_options -.->|"configures auth"| node_auth
node_options -->|"configures provider"| node_observability
node_options -->|"configures retries"| node_retry
node_routeops -.->|"supports list pages"| node_pagination
node_routetx -.->|"supports list pages"| node_pagination
node_generator -->|"creates routes"| node_routeops
node_generator -->|"creates routes"| node_routetx
node_generator -->|"validates inputs"| node_models
node_txbatch -->|"processes transactions"| node_models
node_txbatch -->|"reads request context"| node_sdkctx
node_accounts -->|"formats values"| node_format
node_validation -.->|"validates transaction data"| node_models
node_integrity -->|"checks ledger entities"| node_models
node_concurrent -->|"configures HTTP retries"| node_retry
node_performance -->|"returns structured errors"| node_errors
node_performance -.->|"reports telemetry"| node_observability

click node_client "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/midaz.go"
click node_options "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/midaz_options.go"
click node_v1 "https://github.com/lerianstudio/midaz-sdk-golang/tree/main/entities"
click node_v2 "https://github.com/lerianstudio/midaz-sdk-golang/tree/main/entities"
click node_routeops "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/operation_routes_facade.go"
click node_routetx "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/transaction_routes_facade.go"
click node_models "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/models/model.go"
click node_http "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/http.go"
click node_auth "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/auth/access_manager.go"
click node_retry "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/retry/http.go"
click node_errors "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/errors/errors.go"
click node_pagination "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/iter.go"
click node_generator "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/generator/operation_routes_generator.go"
click node_txbatch "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/transaction/batch.go"
click node_accounts "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/accounts/accounts.go"
click node_validation "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/validation/enhanced.go"
click node_integrity "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/integrity/checker.go"
click node_format "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/format/format.go"
click node_concurrent "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/concurrent/http_batch.go"
click node_performance "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/performance/batch.go"
click node_observability "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/observability/observability.go"
click node_sdkctx "https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/sdkctx/sdkctx.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_options,node_v1,node_v2,node_routeops,node_routetx,node_models,node_pagination toneBlue
class node_http,node_auth,node_retry,node_errors toneAmber
class node_generator,node_txbatch,node_accounts,node_validation,node_integrity,node_format,node_ledgerapi toneMint
class node_concurrent,node_performance,node_observability,node_sdkctx toneRose
class node_app toneIndigo
```

## Components

### Client and services

- [Client construction](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/midaz.go): `midaz.go`
- [Client options](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/midaz_options.go): `midaz_options.go`
- [V1 services](https://github.com/lerianstudio/midaz-sdk-golang/tree/main/entities): `entities`
- [V2 services](https://github.com/lerianstudio/midaz-sdk-golang/tree/main/entities): `entities`
- [Operation routes](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/operation_routes_facade.go): `entities/operation_routes_facade.go`
- [Transaction routes](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/transaction_routes_facade.go): `entities/transaction_routes_facade.go`
- [Typed models](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/models/model.go): `models/model.go`
- [List pagination](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/iter.go): `entities/iter.go`

### Transport and resilience

- [HTTP response layer](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/entities/http.go): `entities/http.go`
- [Access Manager auth](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/auth/access_manager.go): `pkg/auth/access_manager.go`
- [HTTP retries](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/retry/http.go): `pkg/retry/http.go`
- [Structured errors](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/errors/errors.go): `pkg/errors/errors.go`

### Ledger workflows

- [Route generators](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/generator/operation_routes_generator.go): `pkg/generator/operation_routes_generator.go`
- [Transaction batches](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/transaction/batch.go): `pkg/transaction/batch.go`
- [Account helpers](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/accounts/accounts.go): `pkg/accounts/accounts.go`
- [Enhanced validation](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/validation/enhanced.go): `pkg/validation/enhanced.go`
- [Ledger integrity](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/integrity/checker.go): `pkg/integrity/checker.go`
- [Value formatting](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/format/format.go): `pkg/format/format.go`

### Shared capabilities

- [HTTP batching](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/concurrent/http_batch.go): `pkg/concurrent/http_batch.go`
- [Performance batching](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/performance/batch.go): `pkg/performance/batch.go`
- [OpenTelemetry](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/observability/observability.go): `pkg/observability/observability.go`
- [Request context](https://github.com/lerianstudio/midaz-sdk-golang/blob/main/pkg/sdkctx/sdkctx.go): `pkg/sdkctx/sdkctx.go`

### Other components

- **SDK consumer**
- **Midaz ledger API**

## Connections

- SDK consumer → Client construction: constructs (evidence: `README.md`)
- Client construction → Client options: accepts options (evidence: `midaz_options.go`)
- SDK consumer → V1 services: uses (evidence: `README.md`)
- SDK consumer → V2 services: uses (evidence: `README.md`)
- V1 services → Midaz ledger API: requests `/v1` (evidence: `README.md`)
- V2 services → Midaz ledger API: requests `/v2` (evidence: `README.md`)
- Operation routes → Midaz ledger API: calls endpoints (evidence: `entities/operation_routes_facade.go`)
- Transaction routes → Midaz ledger API: calls endpoints (evidence: `entities/transaction_routes_facade.go`)
- Operation routes → Typed models: uses typed inputs (evidence: `entities/operation_routes_facade.go`)
- Transaction routes → Typed models: uses typed inputs (evidence: `entities/transaction_routes_facade.go`)
- V1 services → Operation routes: exposes service
- V2 services → Operation routes: exposes service
- V1 services → Transaction routes: exposes service
- V2 services → Transaction routes: exposes service
- Operation routes → HTTP response layer: decodes responses (evidence: `entities/operation_routes_facade.go`)
- Transaction routes → HTTP response layer: decodes responses (evidence: `entities/transaction_routes_facade.go`)
- HTTP response layer → Structured errors: reports failures
- Client options → Access Manager auth: configures auth
- Client options → OpenTelemetry: configures provider (evidence: `midaz_options.go`)
- Client options → HTTP retries: configures retries (evidence: `midaz_options.go`)
- Operation routes → List pagination: supports list pages
- Transaction routes → List pagination: supports list pages
- Route generators → Operation routes: creates routes (evidence: `pkg/generator/operation_routes_generator.go`)
- Route generators → Transaction routes: creates routes
- Route generators → Typed models: validates inputs (evidence: `pkg/generator/operation_routes_generator.go`)
- Transaction batches → Typed models: processes transactions (evidence: `pkg/transaction/batch.go`)
- Transaction batches → Request context: reads request context (evidence: `pkg/transaction/batch.go`)
- Account helpers → Value formatting: formats values (evidence: `pkg/accounts/accounts.go`)
- Enhanced validation → Typed models: validates transaction data
- Ledger integrity → Typed models: checks ledger entities (evidence: `pkg/integrity/checker.go`)
- HTTP batching → HTTP retries: configures HTTP retries (evidence: `pkg/concurrent/http_batch.go`)
- Performance batching → Structured errors: returns structured errors (evidence: `pkg/performance/batch.go`)
- Performance batching → OpenTelemetry: reports telemetry
