# agorapay/python-sdk architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Python SDK (client library) for the CAPSPAYMENT REST API.
- It provides modules to authenticate, build requests, call payment-related endpoints (account holders, mandates, payins, payouts, transfers, etc.), and deserialize responses into model objects.

##### File‐Structure Analysis
- Top‐level:
- setup.py, requirements.txt, README.md – packaging and documentation
- capspayment/ – main package
- LICENSE, TERMS_AND_CONDITIONS.md
- capspayment/:
- api.py, authentication.py, config.py, base.py, utils.py, version.py
- api_<feature>.py + api_<feature>_model.py pairs for each endpoint
- model.py – shared model base classes

##### Key README Insights
- Initialization: create a CAPSPaymentAPI instance (requires API URL, token URL, credentials).
- Use factory methods (e.g. .payment_account_api()) to get per‐feature API clients.
- Call client methods (e.g. payment_account(payload)) which perform HTTP requests.
- Responses mapped into model objects.

##### Main Components
a. Client Application
– Your code or service that imports and uses `capspayment` SDK.
b. CAPSPayment SDK
- Entry Point: CAPSPaymentAPI (api.py)
- Authentication: authentication.py + config.py
- HTTP Engine: base.py (wraps HTTP calls, headers, token injection)
- API Modules: api_account_holder, api_mandate, api_operations, api_payin, api_payment_account, api_payment_method, api_payout, api_selfcare, api_transfer
- Models: api_*_model.py + model.py
- Utilities: utils.py, version.py
c. External Services
- Token Service (token_url endpoint)
- CAPSPAYMENT REST API (api_url endpoints)
d. Data Flow
1. Client calls CAPSPaymentAPI(...)
2. SDK retrieves OAuth/token from Token Service
3. Client invokes e.g. `.payin_api()` factory method → returns ApiPayin instance
4. Client calls ApiPayin.payment(payload)
5. HTTP Engine sends HTTP request to CAPSPAYMENT REST API with token
6. Response is parsed by api_payin_model into Python objects
7. SDK returns model instance or raw data to client

##### Architectural Patterns & Principles
- Factory Pattern: CAPSPaymentAPI creates per‐feature API clients.
- Separation of Concerns:
- Authentication/configuration separated from HTTP logic
- HTTP transport isolated in base.py
- Serialization/deserialization in model files
- Single Responsibility: each api_<feature>.py handles only its endpoints.
- Dependency Injection: config and auth passed into HTTP engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Application"]:::client

    subgraph "CAPSPayment SDK"
        entryPoint["CAPSPaymentAPI"]:::sdk

        subgraph "Authentication & Config"
            auth["Authentication Module"]:::sdk
            config["Configuration Module"]:::sdk
        end

        subgraph "HTTP Transport"
            http["HTTP Engine"]:::sdk
        end

        subgraph "API Feature Modules"
            acc["Account Holder API"]:::sdk
            man["Mandate API"]:::sdk
            ops["Operations API"]:::sdk
            pin["Pay-in API"]:::sdk
            pac["Payment Account API"]:::sdk
            pmt["Payment Method API"]:::sdk
            pou["Payout API"]:::sdk
            sc["Self-care API"]:::sdk
            trf["Transfer API"]:::sdk
        end

        subgraph "Models & Utilities"
            model["Shared Model Base Classes"]:::sdk
            accm["Account Holder Models"]:::sdk
            manm["Mandate Models"]:::sdk
            opsm["Operations Models"]:::sdk
            pinm["Pay-in Models"]:::sdk
            pacm["Payment Account Models"]:::sdk
            pmtm["Payment Method Models"]:::sdk
            poum["Payout Models"]:::sdk
            scm["Self-care Models"]:::sdk
            trfm["Transfer Models"]:::sdk
            utils["Utilities"]:::sdk
            ver["Version Information"]:::sdk
        end
    end

    token["Token Service"]:::ext
    rest["CAPSPAYMENT REST API"]:::ext

    Client -->|"initialize(api_url, token_url, creds)"| entryPoint
    entryPoint -->|"POST token request"| auth
    auth -->|"use config"| config
    auth -->|"retrieve token"| token
    token -->|"200 OK + token"| entryPoint
    entryPoint -->|"factory: payin_api()"| pin
    pin -->|"call payment(payload)"| http
    http -->|"POST /payin/payment + token"| rest
    rest -->|"200 + JSON"| http
    http -->|"return JSON"| pin
    pin -->|"deserialize"| pinm
    pinm -->|"model instance"| pin
    pin -->|"return model instance"| Client

    click entryPoint "https://github.com/agorapay/python-sdk/blob/main/capspayment/api.py"
    click auth "https://github.com/agorapay/python-sdk/blob/main/capspayment/authentication.py"
    click config "https://github.com/agorapay/python-sdk/blob/main/capspayment/config.py"
    click http "https://github.com/agorapay/python-sdk/blob/main/capspayment/base.py"
    click model "https://github.com/agorapay/python-sdk/blob/main/capspayment/model.py"
    click utils "https://github.com/agorapay/python-sdk/blob/main/capspayment/utils.py"
    click ver "https://github.com/agorapay/python-sdk/blob/main/capspayment/version.py"
    click acc "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_account_holder.py"
    click man "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_mandate.py"
    click ops "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_operations.py"
    click pin "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_payin.py"
    click pac "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_payment_account.py"
    click pmt "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_payment_method.py"
    click pou "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_payout.py"
    click sc "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_selfcare.py"
    click trf "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_transfer.py"
    click accm "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_account_holder_model.py"
    click manm "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_mandate_model.py"
    click opsm "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_operations_model.py"
    click pinm "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_payin_model.py"
    click pacm "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_payment_account_model.py"
    click pmtm "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_payment_method_model.py"
    click poum "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_payout_model.py"
    click scm "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_selfcare_model.py"
    click trfm "https://github.com/agorapay/python-sdk/blob/main/capspayment/api_transfer_model.py"

    classDef sdk fill:#E8F5E9,stroke:#388E3C,color:#1B5E20
    classDef ext fill:#FFEBEE,stroke:#C62828,color:#B71C1C
    classDef client fill:#E3F2FD,stroke:#1976D2,color:#0D47A1
    class entryPoint,auth,config,http,model,utils,ver,acc,man,ops,pin,pac,pmt,pou,sc,trf,accm,manm,opsm,pinm,pacm,pmtm,poum,scm,trfm sdk
    class token,rest ext
    class Client client
```
