# astronomiwe/tbc-sdk-python architecture

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

- Interactive diagram: https://gitdiagram.com/astronomiwe/tbc-sdk-python
- Repository: https://github.com/astronomiwe/tbc-sdk-python

## Overview

tbc-payments is a typed Python SDK for TBC Checkout. A merchant backend builds a payment request, calls either client to create a checkout, and redirects the customer to TBC’s hosted payment page. For callbacks, framework helpers extract the payment ID; the merchant should fetch the payment from TBC before fulfilling an order. The graph includes the shared HTTP/authentication layer and typed models. Relationships come from the excerpts and README; unsampled implementation details are omitted.

Main entry points: [`src/tbc_payments/client.py`](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/client.py) (Sync client), [`src/tbc_payments/async_client.py`](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/async_client.py) (Async client), [`src/tbc_payments/models.py`](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/models.py) (Payment models), [`src/tbc_payments/integrations/fastapi.py`](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/integrations/fastapi.py) (FastAPI adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Checkout clients"]
  node_sync_client["Sync client<br/>[client.py]"]
  node_async_client["Async client<br/>[async_client.py]"]
end

subgraph group_core["Shared SDK core"]
  node_models["Payment models<br/>[models.py]"]
  node_validation["Input validation<br/>[_validation.py]"]
  node_http_core["HTTP and tokens<br/>[_base.py]"]
  node_errors["SDK errors<br/>[exceptions.py]"]
end

subgraph group_callbacks["Callback handling"]
  node_callback_parser["Callback parser<br/>[webhooks.py]"]
  node_fastapi_adapter["FastAPI adapter<br/>[fastapi.py]"]
  node_django_adapter["Django adapter<br/>[django.py]"]
end

node_merchant(("Merchant backend"))
node_customer(("Customer"))
node_tbc_api["TBC Checkout API"]
node_hosted_page["TBC payment page"]

node_merchant -->|"calls"| node_sync_client
node_merchant -->|"calls"| node_async_client
node_sync_client -->|"uses"| node_http_core
node_async_client -->|"uses"| node_http_core
node_sync_client -->|"validates with"| node_validation
node_async_client -->|"validates with"| node_validation
node_sync_client -->|"builds and parses"| node_models
node_async_client -->|"builds and parses"| node_models
node_sync_client -->|"sends requests"| node_tbc_api
node_async_client -->|"sends requests"| node_tbc_api
node_sync_client -->|"returns approval URL"| node_merchant
node_async_client -->|"returns payment"| node_merchant
node_merchant -->|"redirects to checkout"| node_customer
node_customer -->|"pays on"| node_hosted_page
node_tbc_api -->|"hosts checkout"| node_hosted_page
node_http_core -->|"raises"| node_errors
node_models -->|"validates URLs with"| node_validation
node_models -->|"raises"| node_errors
node_tbc_api -->|"notifies callback"| node_fastapi_adapter
node_tbc_api -->|"notifies callback"| node_django_adapter
node_merchant -->|"handles callback with"| node_fastapi_adapter
node_merchant -->|"handles callback with"| node_django_adapter
node_fastapi_adapter -->|"parses with"| node_callback_parser
node_django_adapter -->|"parses with"| node_callback_parser
node_fastapi_adapter -->|"raises"| node_errors
node_django_adapter -->|"raises"| node_errors
node_merchant -->|"fetches payment for verification"| node_sync_client

click node_sync_client "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/client.py"
click node_async_client "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/async_client.py"
click node_models "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/models.py"
click node_validation "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/_validation.py"
click node_http_core "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/_base.py"
click node_errors "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/exceptions.py"
click node_callback_parser "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/webhooks.py"
click node_fastapi_adapter "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/integrations/fastapi.py"
click node_django_adapter "https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/integrations/django.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_models,node_validation,node_http_core,node_errors toneAmber
class node_callback_parser,node_fastapi_adapter,node_django_adapter,node_tbc_api toneMint
class node_merchant,node_customer,node_hosted_page toneIndigo
```

## Components

### Checkout clients

- [Sync client](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/client.py): `src/tbc_payments/client.py`
- [Async client](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/async_client.py): `src/tbc_payments/async_client.py`

### Shared SDK core

- [Payment models](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/models.py): `src/tbc_payments/models.py`
- [Input validation](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/_validation.py): `src/tbc_payments/_validation.py`
- [HTTP and tokens](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/_base.py): `src/tbc_payments/_base.py`
- [SDK errors](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/exceptions.py): `src/tbc_payments/exceptions.py`

### Callback handling

- [Callback parser](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/webhooks.py): `src/tbc_payments/webhooks.py`
- [FastAPI adapter](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/integrations/fastapi.py): `src/tbc_payments/integrations/fastapi.py`
- [Django adapter](https://github.com/astronomiwe/tbc-sdk-python/blob/master/src/tbc_payments/integrations/django.py): `src/tbc_payments/integrations/django.py`

### Other components

- **Merchant backend**
- **Customer**
- **TBC Checkout API**
- **TBC payment page**

## Connections

- Merchant backend → Sync client: calls (evidence: `README.md`)
- Merchant backend → Async client: calls (evidence: `README.md`)
- Sync client → HTTP and tokens: uses (evidence: `src/tbc_payments/client.py`)
- Async client → HTTP and tokens: uses (evidence: `src/tbc_payments/async_client.py`)
- Sync client → Input validation: validates with (evidence: `src/tbc_payments/client.py`)
- Async client → Input validation: validates with (evidence: `src/tbc_payments/async_client.py`)
- Sync client → Payment models: builds and parses (evidence: `src/tbc_payments/client.py`)
- Async client → Payment models: builds and parses (evidence: `src/tbc_payments/async_client.py`)
- Sync client → TBC Checkout API: sends requests (evidence: `src/tbc_payments/client.py`)
- Async client → TBC Checkout API: sends requests (evidence: `src/tbc_payments/async_client.py`)
- Sync client → Merchant backend: returns approval URL (evidence: `README.md`)
- Async client → Merchant backend: returns payment (evidence: `README.md`)
- Merchant backend → Customer: redirects to checkout (evidence: `README.md`)
- Customer → TBC payment page: pays on (evidence: `README.md`)
- TBC Checkout API → TBC payment page: hosts checkout (evidence: `README.md`)
- HTTP and tokens → SDK errors: raises (evidence: `src/tbc_payments/_base.py`)
- Payment models → Input validation: validates URLs with (evidence: `src/tbc_payments/models.py`)
- Payment models → SDK errors: raises (evidence: `src/tbc_payments/models.py`)
- TBC Checkout API → FastAPI adapter: notifies callback (evidence: `README.md`)
- TBC Checkout API → Django adapter: notifies callback (evidence: `README.md`)
- Merchant backend → FastAPI adapter: handles callback with (evidence: `README.md`)
- Merchant backend → Django adapter: handles callback with (evidence: `README.md`)
- FastAPI adapter → Callback parser: parses with (evidence: `src/tbc_payments/integrations/fastapi.py`)
- Django adapter → Callback parser: parses with (evidence: `src/tbc_payments/integrations/django.py`)
- FastAPI adapter → SDK errors: raises (evidence: `src/tbc_payments/integrations/fastapi.py`)
- Django adapter → SDK errors: raises (evidence: `src/tbc_payments/integrations/django.py`)
- Merchant backend → Sync client: fetches payment for verification (evidence: `README.md`)
