# laddertech/sicoob-sdk architecture

> Architecture diagram of the GitHub repository laddertech/sicoob-sdk, 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/laddertech/sicoob-sdk
- Repository: https://github.com/laddertech/sicoob-sdk

## Overview

The Sicoob Python SDK lets an application configure a client for a specific environment and credentials, then perform banking operations such as boleto management, PIX charges, and account queries. The synchronous client exposes these APIs; asynchronous client and domain modules provide a parallel route. Requests use OAuth credentials and HTTP clients to communicate with Sicoob. The README documents additional boleto workflows, including wallet movements and webhooks. Edges follow the available source references and excerpts; unsampled implementation details are not asserted.

Main entry points: [`sicoob/api_client.py`](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/api_client.py) (Sync HTTP client), [`sicoob/async_client.py`](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_client.py) (Async client), [`sicoob/client.py`](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/client.py) (Sync client), [`sicoob/auth/oauth.py`](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/auth/oauth.py) (OAuth authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Client entry points"]
  node_sync_client["Sync client<br/>[client.py]"]
  node_async_client["Async client<br/>[async_client.py]"]
end

subgraph group_domains["Banking operations"]
  node_cobranca["Collection API<br/>[cobranca.py]"]
  node_boleto["Boleto operations<br/>[boleto.py]"]
  node_pix["PIX operations<br/>[pix.py]"]
  node_account["Account operations<br/>[conta_corrente.py]"]
  node_async_boleto["Async boleto<br/>[async_boleto.py]"]
  node_async_pix["Async PIX<br/>[async_pix.py]"]
end

subgraph group_transport["Auth and transport"]
  node_oauth["OAuth authentication<br/>[oauth.py]"]
  node_http_sync["Sync HTTP client<br/>[api_client.py]"]
  node_http_async["Async HTTP client<br/>[async_client.py]"]
end

subgraph group_support["Runtime support"]
  node_config["Environment config<br/>[config.py]"]
  node_credentials["Credential validation<br/>[_credenciais.py]"]
  node_pagination["Pagination<br/>[pagination.py]"]
  node_validation["Input validation<br/>[validation.py]"]
  node_resilience["Retry resilience<br/>[resilience.py]"]
  node_cache["Sync cache<br/>[cache.py]"]
  node_async_cache["Async cache<br/>[async_cache.py]"]
  node_logging["Logging<br/>[logging_config.py]"]
end

node_application(("Application"))
node_sicoob_api{{"Sicoob API"}}

node_application -->|"creates client"| node_sync_client
node_application -->|"uses async client"| node_async_client
node_sync_client -->|"selects environment"| node_config
node_sync_client -->|"validates client ID"| node_credentials
node_sync_client -->|"initializes auth"| node_oauth
node_sync_client -->|"exposes collection"| node_cobranca
node_sync_client -->|"exposes account"| node_account
node_cobranca -->|"creates boleto API"| node_boleto
node_cobranca -->|"creates PIX API"| node_pix
node_oauth -->|"validates client ID"| node_credentials
node_oauth -->|"requests access token"| node_sicoob_api
node_http_sync -->|"gets access token"| node_oauth
node_http_sync -->|"uses environment"| node_config
node_http_sync -->|"creates resilient session"| node_resilience
node_http_sync -->|"sends HTTP requests"| node_sicoob_api
node_boleto -->|"uses API client"| node_http_sync
node_account -->|"uses API client"| node_http_sync
node_pix -->|"uses API client"| node_http_sync
node_pix -->|"fetches paged results"| node_pagination
node_boleto -->|"validates inputs"| node_validation
node_pix -->|"validates inputs"| node_validation
node_account -->|"validates inputs"| node_validation
node_async_client -->|"uses OAuth client"| node_oauth
node_async_client -->|"uses environment"| node_config
node_async_client -->|"validates credentials"| node_credentials
node_async_client -.->|"sends async requests"| node_sicoob_api
node_async_boleto -->|"uses async client"| node_async_client
node_async_pix -->|"uses async client"| node_async_client
node_async_boleto -->|"validates inputs"| node_validation
node_async_pix -->|"validates inputs"| node_validation
node_async_cache -->|"reuses cache"| node_cache
node_http_sync -->|"logs requests"| node_logging
node_oauth -->|"logs authentication"| node_logging

click node_sync_client "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/client.py"
click node_async_client "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_client.py"
click node_config "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/config.py"
click node_credentials "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/_credenciais.py"
click node_oauth "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/auth/oauth.py"
click node_http_sync "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/api_client.py"
click node_http_async "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_client.py"
click node_cobranca "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/cobranca.py"
click node_boleto "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/boleto.py"
click node_pix "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/pix.py"
click node_account "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/conta_corrente.py"
click node_async_boleto "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_boleto.py"
click node_async_pix "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_pix.py"
click node_pagination "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/pagination.py"
click node_validation "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/validation.py"
click node_resilience "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/resilience.py"
click node_cache "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/cache.py"
click node_async_cache "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_cache.py"
click node_logging "https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/logging_config.py"

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_sync_client,node_async_client toneBlue
class node_cobranca,node_boleto,node_pix,node_account,node_async_boleto,node_async_pix toneAmber
class node_oauth,node_http_sync,node_http_async,node_sicoob_api toneMint
class node_config,node_credentials,node_pagination,node_validation,node_resilience,node_cache,node_async_cache,node_logging toneRose
class node_application toneIndigo
```

## Components

### Client entry points

- [Sync client](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/client.py): `sicoob/client.py`
- [Async client](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_client.py): `sicoob/async_client.py`

### Banking operations

- [Collection API](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/cobranca.py): `sicoob/cobranca.py`
- [Boleto operations](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/boleto.py): `sicoob/boleto.py`
- [PIX operations](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/pix.py): `sicoob/pix.py`
- [Account operations](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/conta_corrente.py): `sicoob/conta_corrente.py`
- [Async boleto](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_boleto.py): `sicoob/async_boleto.py`
- [Async PIX](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_pix.py): `sicoob/async_pix.py`

### Auth and transport

- [OAuth authentication](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/auth/oauth.py): `sicoob/auth/oauth.py`
- [Sync HTTP client](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/api_client.py): `sicoob/api_client.py`
- [Async HTTP client](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_client.py): `sicoob/async_client.py`

### Runtime support

- [Environment config](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/config.py): `sicoob/config.py`
- [Credential validation](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/_credenciais.py): `sicoob/_credenciais.py`
- [Pagination](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/pagination.py): `sicoob/pagination.py`
- [Input validation](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/validation.py): `sicoob/validation.py`
- [Retry resilience](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/resilience.py): `sicoob/resilience.py`
- [Sync cache](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/cache.py): `sicoob/cache.py`
- [Async cache](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/async_cache.py): `sicoob/async_cache.py`
- [Logging](https://github.com/laddertech/sicoob-sdk/blob/main/sicoob/logging_config.py): `sicoob/logging_config.py`

### Other components

- **Application**
- **Sicoob API**

## Connections

- Application → Sync client: creates client (evidence: `README.md`)
- Application → Async client: uses async client (evidence: `README.md`)
- Sync client → Environment config: selects environment (evidence: `sicoob/client.py`)
- Sync client → Credential validation: validates client ID (evidence: `sicoob/client.py`)
- Sync client → OAuth authentication: initializes auth (evidence: `sicoob/client.py`)
- Sync client → Collection API: exposes collection (evidence: `sicoob/client.py`)
- Sync client → Account operations: exposes account (evidence: `sicoob/client.py`)
- Collection API → Boleto operations: creates boleto API (evidence: `sicoob/cobranca.py`)
- Collection API → PIX operations: creates PIX API (evidence: `sicoob/cobranca.py`)
- OAuth authentication → Credential validation: validates client ID (evidence: `sicoob/auth/oauth.py`)
- OAuth authentication → Sicoob API: requests access token (evidence: `sicoob/auth/oauth.py`)
- Sync HTTP client → OAuth authentication: gets access token (evidence: `sicoob/api_client.py`)
- Sync HTTP client → Environment config: uses environment (evidence: `sicoob/api_client.py`)
- Sync HTTP client → Retry resilience: creates resilient session (evidence: `sicoob/api_client.py`)
- Sync HTTP client → Sicoob API: sends HTTP requests (evidence: `sicoob/api_client.py`)
- Boleto operations → Sync HTTP client: uses API client (evidence: `sicoob/boleto.py`)
- Account operations → Sync HTTP client: uses API client (evidence: `sicoob/conta_corrente.py`)
- PIX operations → Sync HTTP client: uses API client (evidence: `sicoob/pix.py`)
- PIX operations → Pagination: fetches paged results (evidence: `sicoob/pix.py`)
- Boleto operations → Input validation: validates inputs (evidence: `sicoob/boleto.py`)
- PIX operations → Input validation: validates inputs (evidence: `sicoob/pix.py`)
- Account operations → Input validation: validates inputs (evidence: `sicoob/conta_corrente.py`)
- Async client → OAuth authentication: uses OAuth client (evidence: `sicoob/async_client.py`)
- Async client → Environment config: uses environment (evidence: `sicoob/async_client.py`)
- Async client → Credential validation: validates credentials (evidence: `sicoob/async_client.py`)
- Async client → Sicoob API: sends async requests
- Async boleto → Async client: uses async client (evidence: `sicoob/async_boleto.py`)
- Async PIX → Async client: uses async client (evidence: `sicoob/async_pix.py`)
- Async boleto → Input validation: validates inputs (evidence: `sicoob/async_boleto.py`)
- Async PIX → Input validation: validates inputs (evidence: `sicoob/async_pix.py`)
- Async cache → Sync cache: reuses cache (evidence: `sicoob/async_cache.py`)
- Sync HTTP client → Logging: logs requests (evidence: `sicoob/api_client.py`)
- OAuth authentication → Logging: logs authentication (evidence: `sicoob/auth/oauth.py`)
