# supabase/storage architecture

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

- Interactive diagram: https://gitdiagram.com/supabase/storage
- Repository: https://github.com/supabase/storage

## Overview

##### Main Components

a. Client Interface Layer
- HTTP/REST API endpoints
- TUS Protocol handler
- S3 Compatible API interface

b. Authentication & Authorization Layer
- JWT authentication
- API Key validation
- SignatureV4 verification (for S3)
- Row Level Security (RLS) integration

c. Core Service Layer
- Storage Service Manager
- Object Manager
- Bucket Manager
- Renderer Service (for image transformations)
- Event System

d. Backend Storage Layer
- S3-compatible storage backend
- File system storage backend
- Database metadata storage (PostgreSQL)

e. Monitoring & Infrastructure
- OpenTelemetry integration
- Prometheus metrics
- Grafana dashboards
- PubSub system

##### Relationships and Data Flow

- Client requests flowing through authentication
- Storage operations passing through the core service layer
- Metadata operations to PostgreSQL
- Object storage operations to backend storage
- Event notifications through PubSub
- Monitoring data flow to observability stack

##### Key Technical Elements

Specific components from the codebase:
- Storage Backend Adapters (src/storage/backend)
- Database Adapters (src/storage/database)
- Protocol Handlers (src/storage/protocols)
- Renderer Service (src/storage/renderer)
- Event System (src/storage/events)

##### Additional Details

Annotations for:
- Security boundaries
- Authentication flows
- Transformation pipelines
- Event workflows
- Migration processes

##### The comprehensive monitoring and observability setup

This will create a clear and accurate representation of the Supabase Storage Engine's architecture while maintaining the necessary level of detail for a principal software engineer to understand the system's complete design.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph Clients
        HTTP[HTTP/REST Clients]:::client
        TUS[TUS Clients]:::client
        S3C[S3 Compatible Clients]:::client
    end

    %% Protocol Handler Layer
    subgraph ProtocolHandlers[Protocol Handlers]
        REST["HTTP/REST Routes"]:::protocol
        TUSP["TUS Protocol Handler"]:::protocol
        S3P["S3 Protocol Handler"]:::protocol
    end

    %% Security Layer
    subgraph Security[Security Components]
        JWT["JWT Handler"]:::security
        APIKEY["API Key Handler"]:::security
        SIG4["SignatureV4"]:::security
    end

    %% Core Services Layer
    subgraph CoreServices[Core Services]
        AUTH["Authentication Service"]:::core
        STORAGE["Storage Service"]:::core
        RENDER["Renderer Service"]:::core
        QUEUE["Queue System"]:::core
        EVENT["Event System"]:::core
    end

    %% Backend Layer
    subgraph Backend[Backend Services]
        S3B["S3 Backend"]:::backend
        FILEB["File Backend"]:::backend
        DB["Multi-tenant DB Handler"]:::database
        POSTGRES[(PostgreSQL)]:::database
    end

    %% Monitoring Layer
    subgraph Monitoring[Monitoring & Observability]
        METRICS["Metrics System"]:::monitoring
        OTEL["OpenTelemetry"]:::monitoring
        PROM["Prometheus"]:::monitoring
        GRAF["Grafana"]:::monitoring
    end

    %% Additional Components
    subgraph Additional[Additional Components]
        MIGRATE["Migration System"]:::additional
        RATELIMIT["Rate Limiter"]:::additional
        WEBHOOK["Webhook System"]:::additional
        IMGPROC["Image Processor"]:::additional
        TRANSFORM["Transformation Schemas"]:::additional
    end

    %% Client to Protocol Handler Connections
    HTTP --> REST
    TUS --> TUSP
    S3C --> S3P

    %% Protocol Handlers to Security
    REST --> JWT & APIKEY
    TUSP --> JWT & APIKEY
    S3P --> SIG4

    %% Security to Core Services
    JWT --> AUTH
    APIKEY --> AUTH
    SIG4 --> AUTH

    %% Protocol Handlers to Core Services
    REST --> STORAGE
    TUSP --> STORAGE
    S3P --> STORAGE

    %% Core Service Interactions
    STORAGE --> RENDER
    STORAGE --> EVENT
    EVENT --> QUEUE
    RENDER --> RATELIMIT
    RENDER --> IMGPROC
    IMGPROC --> TRANSFORM

    %% Backend Connections
    STORAGE --> S3B & FILEB
    STORAGE --> DB
    DB --> POSTGRES
    EVENT --> WEBHOOK

    %% Monitoring Connections
    METRICS --> OTEL
    OTEL --> PROM
    PROM --> GRAF

    %% Migration System
    MIGRATE --> DB

    %% Click Events
    click REST "https://github.com/supabase/storage/tree/master/src/http/routes/"
    click TUSP "https://github.com/supabase/storage/tree/master/src/storage/protocols/tus/"
    click S3P "https://github.com/supabase/storage/tree/master/src/storage/protocols/s3/"
    click AUTH "https://github.com/supabase/storage/tree/master/src/internal/auth/"
    click STORAGE "https://github.com/supabase/storage/blob/master/src/storage/storage.ts"
    click RENDER "https://github.com/supabase/storage/tree/master/src/storage/renderer/"
    click QUEUE "https://github.com/supabase/storage/tree/master/src/internal/queue/"
    click EVENT "https://github.com/supabase/storage/tree/master/src/storage/events/"
    click S3B "https://github.com/supabase/storage/blob/master/src/storage/backend/s3.ts"
    click FILEB "https://github.com/supabase/storage/blob/master/src/storage/backend/file.ts"
    click DB "https://github.com/supabase/storage/tree/master/src/internal/database/"
    click METRICS "https://github.com/supabase/storage/tree/master/src/internal/monitoring/"
    click OTEL "https://github.com/supabase/storage/blob/master/src/internal/monitoring/otel.ts"
    click PROM "https://github.com/supabase/storage/blob/master/monitoring/prometheus/prometheus.yml"
    click GRAF "https://github.com/supabase/storage/tree/master/monitoring/grafana/dashboards/"
    click JWT "https://github.com/supabase/storage/blob/master/src/http/plugins/jwt.ts"
    click APIKEY "https://github.com/supabase/storage/blob/master/src/http/plugins/apikey.ts"
    click SIG4 "https://github.com/supabase/storage/blob/master/src/http/plugins/signature-v4.ts"
    click MIGRATE "https://github.com/supabase/storage/tree/master/migrations/"
    click RATELIMIT "https://github.com/supabase/storage/blob/master/src/http/routes/render/rate-limiter.ts"
    click WEBHOOK "https://github.com/supabase/storage/blob/master/src/storage/events/webhook.ts"
    click IMGPROC "https://github.com/supabase/storage/blob/master/src/storage/renderer/image.ts"
    click TRANSFORM "https://github.com/supabase/storage/blob/master/src/http/schemas/transformations.ts"

    %% Styles
    classDef client fill:#2196F3,stroke:#1565C0,color:white
    classDef protocol fill:#4CAF50,stroke:#2E7D32,color:white
    classDef security fill:#F44336,stroke:#C62828,color:white
    classDef core fill:#009688,stroke:#00695C,color:white
    classDef backend fill:#FFC107,stroke:#FFA000,color:black
    classDef database fill:#673AB7,stroke:#4527A0,color:white
    classDef monitoring fill:#FF5722,stroke:#D84315,color:white
    classDef additional fill:#795548,stroke:#4E342E,color:white

    %% Legend
    subgraph Legend
        C1[Client Layer]:::client
        P1[Protocol Layer]:::protocol
        S1[Security Layer]:::security
        CS1[Core Services]:::core
        B1[Backend Services]:::backend
        D1[Database]:::database
        M1[Monitoring]:::monitoring
        A1[Additional Components]:::additional
    end
```
