# stasfilin/sendcloud architecture

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

- Interactive diagram: https://gitdiagram.com/stasfilin/sendcloud
- Repository: https://github.com/stasfilin/sendcloud

## Overview

##### Project type and purpose
- This is an open-source Python client library (“sendcloud-python”) that wraps the Sendcloud REST API.
- Its purpose is to give other Python developers a convenient, object-oriented way to call Sendcloud endpoints (parcels, labels, returns, invoices, etc.) without writing raw HTTP code.

##### File-structure analysis
- Top-level:
- sendcloud/                  ← main package
– __init__.py               ← global settings (API_KEY, API_SECRET)
– __version__.py           ← version metadata
– classes/                  ← resource clients (Brands, Parcels, Invoices, …)
– http/                     ← HTTP client, exception definitions
- docs/                       ← auto-generated Sphinx docs
- tests/                      ← pytest test suite + JSON fixtures
- .github/workflows/          ← CI pipelines (publish to PyPI, run tests)
- setup.py & requirements/    ← build/install configuration

##### README insights
- Confirms it is an “Unofficial Python Library” for Sendcloud API.
- Shows simple developer usage: set API_KEY/SECRET on module, call resource methods to GET/POST.
- Mentions develop mode, test command.

##### Main components
a. User Application
– Calls into the sendcloud package’s public classes.
b. sendcloud.classes layer
– One class per endpoint group (Parcels, Labels, Returns, etc.)
– Exposes methods like get_parcels(), create_parcel()
c. sendcloud.http layer
– HTTPClient: builds requests, attaches auth, sends via requests (or urllib3)
– Exceptions: maps HTTP error codes to Python exceptions
d. External Sendcloud REST API
– The actual HTTP endpoints hosted by Sendcloud
e. Supporting tools (optional)
– Sphinx docs generator (docs/)
– pytest test suite (tests/)
– CI/CD pipelines (.github/workflows)

##### Relationships & data flow
(invokes business operation)
(assembles URL, headers, payload JSON)
(over HTTPS, including API_KEY/SECRET for auth)
(JSON response or error code)
(parses JSON into Python dict or raises exception)
(returns data or throws exception)

##### Architectural patterns & design principles
- Layered Architecture:
1. Public API layer (resource classes)
2. Transport/Adapter layer (HTTPClient)
3. External integration (REST API)
- Single Responsibility per class: each class handles one resource/domain
- Adapter pattern: HTTPClient adapts Python calls to HTTP requests
- Exceptions modeled per HTTP error

## Diagram (Mermaid)

```mermaid
graph TB
    %% Application Layer
    UserApp["User Application"]:::external

    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        Init["__init__.py"]:::cfg
        Version["__version__.py"]:::cfg
        Brands["Brands"]:::public
        Parcels["Parcels"]:::public
        Labels["Labels"]:::public
        Returns["Returns"]:::public
        Invoices["Invoices"]:::public
        SenderAddress["Sender Address"]:::public
        ShippingMethods["Shipping Methods"]:::public
        Users["Users"]:::public
        Webhooks["Webhooks"]:::public
        IntegrationsOrders["Integrations & Orders"]:::public
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        HTTPClient["HTTPClient"]:::transport
        Exceptions["Exceptions"]:::transport
    end

    %% External Service
    External["Sendcloud REST API"]:::external

    %% Supporting Tools
    subgraph "Supporting Tools"
        direction TB
        Docs["Sphinx Docs"]:::docs
        Tests["pytest Tests"]:::tests
        CI["GitHub Actions"]:::ci
        Setup["setup.py & requirements"]:::cfg
    end

    %% Connections
    UserApp -->|calls resource method| Parcels
    Parcels -->|uses HTTPClient| HTTPClient
    HTTPClient -->|JSON request + Auth headers| External
    External -->|JSON response or error| HTTPClient
    HTTPClient -->|parse JSON or raise| Parcels
    Parcels -->|returns data or exception| UserApp

    %% Click Events
    click Init "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/__init__.py"
    click Version "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/__version__.py"
    click Brands "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/brands.py"
    click Parcels "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/parcels.py"
    click Labels "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/labels.py"
    click Returns "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/returns.py"
    click Invoices "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/invoices.py"
    click SenderAddress "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/sender_address.py"
    click ShippingMethods "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/shipping_methods.py"
    click Users "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/users.py"
    click Webhooks "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/webhooks.py"
    click IntegrationsOrders "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/classes/integrations_and_orders.py"
    click HTTPClient "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/http/client.py"
    click Exceptions "https://github.com/stasfilin/sendcloud/blob/master/sendcloud/http/exceptions.py"
    click Docs "https://github.com/stasfilin/sendcloud/blob/master/docs/index.html"
    click Tests "https://github.com/stasfilin/sendcloud/blob/master/tests/testcase.py"
    click CI "https://github.com/stasfilin/sendcloud/blob/master/.github/workflows/pythonpackage.yml"
    click Setup "https://github.com/stasfilin/sendcloud/blob/master/setup.py"

    %% Styles
    classDef public fill:#ccffcc,stroke:#009900
    classDef transport fill:#cce5ff,stroke:#0066cc
    classDef external fill:#ffe0b3,stroke:#cc8400
    classDef cfg fill:#e6e6e6,stroke:#999999
    classDef docs fill:#f2e6ff,stroke:#9933cc
    classDef tests fill:#ffffcc,stroke:#cccc00
    classDef ci fill:#f0f0f0,stroke:#666666
```
