# rederici/cloud-storage-api architecture

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

- Interactive diagram: https://gitdiagram.com/rederici/cloud-storage-api
- Repository: https://github.com/rederici/cloud-storage-api

## Overview

Cloud Storage API provides authenticated, user-scoped file and directory operations over S3-compatible storage. The principal workflow is an HTTP request through storage routes and service validation/operations to the S3 repository; authentication routes establish sessions used to authorize user requests. The graph also preserves account/session persistence, infrastructure wiring, health routing, and S3 initialization. Source excerpts show key calls, but several adapters and health handlers were not sampled, so uncertain links are omitted.

Main entry points: [`src/cloud_storage/app/bootstrap.py`](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/app/bootstrap.py) (App Bootstrap), [`src/cloud_storage/auth/service.py`](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/service.py) (Auth Service), [`src/cloud_storage/storage/infrastructure/s3/provider.py`](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/infrastructure/s3/provider.py) (Storage Wiring), [`src/cloud_storage/storage/http/routes.py`](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/http/routes.py) (Storage Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_storage_routes["Storage Routes<br/>[routes.py]"]
  node_auth_routes["Auth Routes<br/>[routes.py]"]
  node_auth_deps["Auth Dependencies<br/>[dependencies.py]"]
  node_health["Health Router<br/>[router.py]"]
  node_http_errors["HTTP Error Mapping"]
end

subgraph group_domain["Domain Services"]
  node_storage_service["Storage Service<br/>[service.py]"]
  node_storage_types["Storage Paths &amp; Types<br/>[types.py]"]
  node_auth_service["Auth Service<br/>[service.py]"]
  node_auth_entities["Accounts &amp; Sessions<br/>[entities.py]"]
end

subgraph group_adapters["Storage Adapters"]
  node_storage_repo["S3 Storage Repository<br/>[repository.py]"]
  node_bucket_init["Bucket Initializer<br/>[initializer.py]"]
  node_storage_provider["Storage Wiring<br/>[provider.py]"]
  node_account_repo["Account Repository<br/>[repository.py]"]
  node_session_repo["Session Repository<br/>[repository.py]"]
  node_password_hash["Password Hasher<br/>[hasher.py]"]
end

subgraph group_platform["Infrastructure"]
  node_bootstrap["App Bootstrap<br/>[bootstrap.py]"]
  node_config["Application Config<br/>[models.py]"]
  node_s3[("S3-Compatible Store")]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_client(("API Client"))

node_client -->|"requests app"| node_bootstrap
node_bootstrap -->|"registers"| node_storage_routes
node_bootstrap -->|"registers"| node_auth_routes
node_bootstrap -->|"registers"| node_health
node_bootstrap -->|"registers handlers"| node_http_errors
node_storage_routes -->|"uses identity"| node_auth_deps
node_storage_routes -->|"calls operations"| node_storage_service
node_auth_routes -->|"calls auth"| node_auth_service
node_auth_deps -->|"resolves sessions"| node_auth_service
node_storage_service -->|"delegates storage"| node_storage_repo
node_storage_service -->|"scopes paths"| node_storage_types
node_storage_repo -->|"reads and writes"| node_s3
node_storage_provider -->|"provides repository"| node_storage_repo
node_storage_provider -->|"configures initializer"| node_bucket_init
node_bucket_init -.->|"initializes bucket"| node_s3
node_auth_service -->|"uses accounts"| node_account_repo
node_auth_service -->|"uses sessions"| node_session_repo
node_auth_service -->|"hashes passwords"| node_password_hash
node_account_repo -.->|"persists accounts"| node_postgres
node_session_repo -.->|"persists sessions"| node_redis
node_bootstrap -->|"loads settings"| node_config
node_storage_provider -->|"reads settings"| node_config
node_auth_service -->|"uses domain records"| node_auth_entities

click node_bootstrap "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/app/bootstrap.py"
click node_storage_routes "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/http/routes.py"
click node_auth_routes "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/http/routes.py"
click node_auth_deps "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/http/dependencies.py"
click node_health "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/health/http/router.py"
click node_http_errors "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/api/http/exception_handler.py"
click node_storage_service "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/service.py"
click node_storage_types "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/types.py"
click node_auth_service "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/service.py"
click node_auth_entities "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/entities.py"
click node_storage_repo "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/infrastructure/s3/repository.py"
click node_bucket_init "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/infrastructure/s3/initializer.py"
click node_storage_provider "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/infrastructure/s3/provider.py"
click node_account_repo "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/infrastructure/sqlalchemy/repository.py"
click node_session_repo "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/infrastructure/redis/repository.py"
click node_password_hash "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/infrastructure/argon2/hasher.py"
click node_config "https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/config/models.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_storage_routes,node_auth_routes,node_auth_deps,node_health,node_http_errors,node_client toneBlue
class node_storage_service,node_storage_types,node_auth_service,node_auth_entities toneAmber
class node_storage_repo,node_bucket_init,node_storage_provider,node_account_repo,node_session_repo,node_password_hash toneMint
class node_bootstrap,node_config,node_s3,node_postgres,node_redis toneRose
```

## Components

### HTTP API

- [Storage Routes](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/http/routes.py): `src/cloud_storage/storage/http/routes.py`
- [Auth Routes](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/http/routes.py): `src/cloud_storage/auth/http/routes.py`
- [Auth Dependencies](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/http/dependencies.py): `src/cloud_storage/auth/http/dependencies.py`
- [Health Router](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/health/http/router.py): `src/cloud_storage/health/http/router.py`
- [HTTP Error Mapping](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/api/http/exception_handler.py): `src/cloud_storage/api/http/exception_handler.py`

### Domain Services

- [Storage Service](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/service.py): `src/cloud_storage/storage/service.py`
- [Storage Paths & Types](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/types.py): `src/cloud_storage/storage/types.py`
- [Auth Service](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/service.py): `src/cloud_storage/auth/service.py`
- [Accounts & Sessions](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/entities.py): `src/cloud_storage/auth/entities.py`

### Storage Adapters

- [S3 Storage Repository](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/infrastructure/s3/repository.py): `src/cloud_storage/storage/infrastructure/s3/repository.py`
- [Bucket Initializer](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/infrastructure/s3/initializer.py): `src/cloud_storage/storage/infrastructure/s3/initializer.py`
- [Storage Wiring](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/storage/infrastructure/s3/provider.py): `src/cloud_storage/storage/infrastructure/s3/provider.py`
- [Account Repository](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/infrastructure/sqlalchemy/repository.py): `src/cloud_storage/auth/infrastructure/sqlalchemy/repository.py`
- [Session Repository](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/infrastructure/redis/repository.py): `src/cloud_storage/auth/infrastructure/redis/repository.py`
- [Password Hasher](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/auth/infrastructure/argon2/hasher.py): `src/cloud_storage/auth/infrastructure/argon2/hasher.py`

### Infrastructure

- [App Bootstrap](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/app/bootstrap.py): `src/cloud_storage/app/bootstrap.py`
- [Application Config](https://github.com/rederici/cloud-storage-api/blob/main/src/cloud_storage/config/models.py): `src/cloud_storage/config/models.py`
- **S3-Compatible Store**
- **PostgreSQL**
- **Redis**

### Other components

- **API Client**

## Connections

- API Client → App Bootstrap: requests app (evidence: `src/cloud_storage/app/bootstrap.py`)
- App Bootstrap → Storage Routes: registers (evidence: `src/cloud_storage/app/bootstrap.py`)
- App Bootstrap → Auth Routes: registers (evidence: `src/cloud_storage/app/bootstrap.py`)
- App Bootstrap → Health Router: registers (evidence: `src/cloud_storage/app/bootstrap.py`)
- App Bootstrap → HTTP Error Mapping: registers handlers (evidence: `src/cloud_storage/app/bootstrap.py`)
- Storage Routes → Auth Dependencies: uses identity (evidence: `src/cloud_storage/storage/http/routes.py`)
- Storage Routes → Storage Service: calls operations (evidence: `src/cloud_storage/storage/http/routes.py`)
- Auth Routes → Auth Service: calls auth (evidence: `src/cloud_storage/auth/http/routes.py`)
- Auth Dependencies → Auth Service: resolves sessions (evidence: `src/cloud_storage/auth/http/dependencies.py`)
- Storage Service → S3 Storage Repository: delegates storage (evidence: `src/cloud_storage/storage/service.py`)
- Storage Service → Storage Paths & Types: scopes paths (evidence: `src/cloud_storage/storage/service.py`)
- S3 Storage Repository → S3-Compatible Store: reads and writes (evidence: `src/cloud_storage/storage/infrastructure/s3/repository.py`)
- Storage Wiring → S3 Storage Repository: provides repository (evidence: `src/cloud_storage/storage/infrastructure/s3/provider.py`)
- Storage Wiring → Bucket Initializer: configures initializer (evidence: `src/cloud_storage/storage/infrastructure/s3/provider.py`)
- Bucket Initializer → S3-Compatible Store: initializes bucket (evidence: `src/cloud_storage/storage/infrastructure/s3/initializer.py`)
- Auth Service → Account Repository: uses accounts (evidence: `src/cloud_storage/auth/service.py`)
- Auth Service → Session Repository: uses sessions (evidence: `src/cloud_storage/auth/service.py`)
- Auth Service → Password Hasher: hashes passwords (evidence: `src/cloud_storage/auth/service.py`)
- Account Repository → PostgreSQL: persists accounts
- Session Repository → Redis: persists sessions
- App Bootstrap → Application Config: loads settings (evidence: `src/cloud_storage/app/bootstrap.py`)
- Storage Wiring → Application Config: reads settings (evidence: `src/cloud_storage/storage/infrastructure/s3/provider.py`)
- Auth Service → Accounts & Sessions: uses domain records (evidence: `src/cloud_storage/auth/service.py`)
