# thumbor/thumbor-aws architecture

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

- Interactive diagram: https://gitdiagram.com/thumbor/thumbor-aws
- Repository: https://github.com/thumbor/thumbor-aws

## Overview

thumbor-aws is a set of independently configurable Thumbor extensions for S3: loading source images, storing originals and associated metadata, and storing generated results. Thumbor selects the extensions through its configuration; each extension uses shared S3-client functionality, while path normalization is visible in the loader and original-image storage excerpts. The README documents the result-storage capability and its S3 role, but its implementation was not sampled, so its internal calls are not shown.

Main entry points: [`thumbor_aws/loader.py`](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/loader.py) (Source image loader), [`thumbor_aws/storage.py`](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/storage.py) (Original storage), [`thumbor_aws/s3_client.py`](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/s3_client.py) (S3 client), [`thumbor_aws/result_storage.py`](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/result_storage.py) (Result storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extensions["Thumbor extensions"]
  node_loader["Source image loader<br/>[loader.py]"]
  node_storage["Original storage<br/>[storage.py]"]
  node_result_storage["Result storage<br/>[result_storage.py]"]
end

subgraph group_shared["Shared infrastructure"]
  node_config["Extension configuration<br/>[config.py]"]
  node_s3_client["S3 client<br/>[s3_client.py]"]
  node_path_normalizer["Path normalization<br/>[utils.py]"]
end

subgraph group_external["External systems"]
  node_s3[("AWS S3")]
end

node_thumbor(("Thumbor service"))

node_thumbor -->|"configures loader"| node_loader
node_thumbor -->|"configures storage"| node_storage
node_thumbor -->|"configures results"| node_result_storage
node_loader -->|"defines settings"| node_config
node_storage -->|"defines settings"| node_config
node_loader -->|"fetches images"| node_s3_client
node_storage -->|"stores and fetches"| node_s3_client
node_loader -->|"normalizes keys"| node_path_normalizer
node_storage -->|"normalizes keys"| node_path_normalizer
node_s3_client -.->|"accesses objects"| node_s3
node_result_storage -->|"stores results"| node_s3

click node_loader "https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/loader.py"
click node_storage "https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/storage.py"
click node_result_storage "https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/result_storage.py"
click node_config "https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/config.py"
click node_s3_client "https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/s3_client.py"
click node_path_normalizer "https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/utils.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_loader,node_storage,node_result_storage toneBlue
class node_config,node_s3_client,node_path_normalizer toneAmber
class node_s3 toneMint
class node_thumbor toneIndigo
```

## Components

### Thumbor extensions

- [Source image loader](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/loader.py): `thumbor_aws/loader.py`
- [Original storage](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/storage.py): `thumbor_aws/storage.py`
- [Result storage](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/result_storage.py): `thumbor_aws/result_storage.py`

### Shared infrastructure

- [Extension configuration](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/config.py): `thumbor_aws/config.py`
- [S3 client](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/s3_client.py): `thumbor_aws/s3_client.py`
- [Path normalization](https://github.com/thumbor/thumbor-aws/blob/main/thumbor_aws/utils.py): `thumbor_aws/utils.py`

### External systems

- **AWS S3**

### Other components

- **Thumbor service**

## Connections

- Thumbor service → Source image loader: configures loader (evidence: `README.md`)
- Thumbor service → Original storage: configures storage (evidence: `README.md`)
- Thumbor service → Result storage: configures results (evidence: `README.md`)
- Source image loader → Extension configuration: defines settings (evidence: `thumbor_aws/loader.py`)
- Original storage → Extension configuration: defines settings (evidence: `thumbor_aws/storage.py`)
- Source image loader → S3 client: fetches images (evidence: `thumbor_aws/loader.py`)
- Original storage → S3 client: stores and fetches (evidence: `thumbor_aws/storage.py`)
- Source image loader → Path normalization: normalizes keys (evidence: `thumbor_aws/loader.py`)
- Original storage → Path normalization: normalizes keys (evidence: `thumbor_aws/storage.py`)
- S3 client → AWS S3: accesses objects (evidence: `README.md`)
- Result storage → AWS S3: stores results (evidence: `README.md`)