# versity/versitygw architecture

> Architecture diagram of the GitHub repository versity/versitygw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/versity/versitygw
- Repository: https://github.com/versity/versitygw

## Overview

##### Main Components Identification

The system should be represented with these key components:

a) API Layer:
- S3 API Server (s3api/)
- Admin API Server (s3api/admin-server.go)
- Authentication/Authorization (auth/)

b) Core Services:
- Backend Providers
- POSIX
- Azure
- S3Proxy
- ScoutFS
- Event System (s3event/)
- Metrics System (metrics/)
- Logging System (s3log/)

c) Supporting Components:
- AWS Compatibility Layer (aws/)
- Error Handling (s3err/)
- Response Formatting (s3response/)
- Select Operations (s3select/)

**┌─ Client Layer ─────────────────────┐**
- S3 Clients / Applications          │
- ┬───────────────────┘
- ↓
**┌─ Gateway Layer ────────────────────┐**
- ┌─ API Handlers ─┐  ┌─ Security ─┐ │
- S3 API       │  │ - Auth     │ │
- Admin API    │  │ - ACL      │ │
- ┘  └───────────┘ │
- ┌─ Core Services ─────────────────┐│
- Events                        ││
- Metrics                       ││
- Logging                       ││
- ┘│
- ┬───────────────────┘
- ↓
**┌─ Storage Layer ────────────────────┐**
- ┌─────┐ ┌───────┐ ┌────┐ ┌──────┐ │
- POSIX│ │Azure  │ │S3  │ │Scout │ │
- ┘ └───────┘ └────┘ └──────┘ │
- ┘

##### Connection Types

- Double lines: Data streaming

##### Important Details

a) Middleware Chain (from s3api/middlewares/):
- Authentication
- ACL parsing
- Body reading
- Chunking
- Logging
- MD5 verification
- URL decoding

b) Backend Interface (backend/backend.go):
- Common interface that all storage backends implement
- Plugin architecture for extensibility

c) Event System Integration:
- Supported event destinations (Kafka, NATS, Webhook)
- Event flow from operations to consumers

##### Scaling and High Availability

A section showing:
- Multiple gateway instances
- Load balancer integration
- Backend scaling capabilities

- Stateless architecture
- Modular backend support
- High performance
- AWS S3 compatibility
- Security integration

Remember to maintain a balance between detail and clarity, focusing on the architectural components that are most important for understanding the system's operation and integration points.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph CL["Client Layer"]
        S3C[S3 Clients]
        Apps[Applications]
    end

    %% Gateway Layer
    subgraph GL["Gateway Layer"]
        GW["Gateway Entry"]:::main
        
        subgraph API["API Layer"]
            S3API["S3 API Server"]:::api
            AdminAPI["Admin API Server"]:::api
            Auth["Authentication"]:::security
        end
        
        subgraph MW["Middleware Chain"]
            AuthMW["Auth Middleware"]:::security
            ACL["ACL Parsing"]:::security
            BodyRead["Body Reading"]:::middleware
            Chunk["Chunking"]:::middleware
            LogMW["Logging"]:::middleware
            MD5["MD5 Verification"]:::middleware
            URLDec["URL Decoding"]:::middleware
        end
        
        subgraph CS["Core Services"]
            Event["Event System"]:::core
            Metrics["Metrics System"]:::core
            Logging["Logging System"]:::core
        end
        
        subgraph SUP["Supporting Services"]
            AWSCompat["AWS Compatibility"]:::support
            ErrHandle["Error Handling"]:::support
            RespFormat["Response Formatting"]:::support
            SelectOps["Select Operations"]:::support
        end
        
        subgraph ES["Event Services"]
            Kafka["Kafka Events"]:::event
            NATS["NATS Events"]:::event
            Webhook["Webhook Events"]:::event
        end
        
        subgraph MS["Metrics Services"]
            DStatsD["DogStatsD"]:::metrics
            StatsD["StatsD"]:::metrics
        end
    end

    %% Storage Layer
    subgraph SL["Storage Layer"]
        BackendIF["Backend Interface"]:::interface
        POSIX["POSIX Storage"]:::storage
        Azure["Azure Storage"]:::storage
        S3Proxy["S3 Proxy"]:::storage
        ScoutFS["Scout FS"]:::storage
    end

    %% Connections
    S3C & Apps --> GW
    GW --> S3API & AdminAPI
    S3API & AdminAPI --> Auth
    Auth --> MW
    MW --> CS
    CS --> SUP
    Event --> ES
    Metrics --> MS
    CS --> BackendIF
    BackendIF --> POSIX & Azure & S3Proxy & ScoutFS

    %% Styles
    classDef main fill:#f9f,stroke:#333
    classDef api fill:#3498db,stroke:#333
    classDef security fill:#f1c40f,stroke:#333
    classDef middleware fill:#95a5a6,stroke:#333
    classDef core fill:#e67e22,stroke:#333
    classDef support fill:#7f8c8d,stroke:#333
    classDef event fill:#2ecc71,stroke:#333
    classDef metrics fill:#9b59b6,stroke:#333
    classDef storage fill:#1abc9c,stroke:#333
    classDef interface fill:#34495e,stroke:#333

    %% Click Events
    click GW "https://github.com/versity/versitygw/blob/main/cmd/versitygw/main.go"
    click S3API "https://github.com/versity/versitygw/tree/main/s3api"
    click AdminAPI "https://github.com/versity/versitygw/blob/main/s3api/admin-server.go"
    click Auth "https://github.com/versity/versitygw/tree/main/auth"
    click Event "https://github.com/versity/versitygw/tree/main/s3event"
    click Metrics "https://github.com/versity/versitygw/tree/main/metrics"
    click Logging "https://github.com/versity/versitygw/tree/main/s3log"
    click AWSCompat "https://github.com/versity/versitygw/tree/main/aws"
    click ErrHandle "https://github.com/versity/versitygw/tree/main/s3err"
    click RespFormat "https://github.com/versity/versitygw/tree/main/s3response"
    click SelectOps "https://github.com/versity/versitygw/tree/main/s3select"
    click AuthMW "https://github.com/versity/versitygw/blob/main/s3api/middlewares/authentication.go"
    click BackendIF "https://github.com/versity/versitygw/blob/main/backend/backend.go"
    click POSIX "https://github.com/versity/versitygw/tree/main/backend/posix"
    click Azure "https://github.com/versity/versitygw/tree/main/backend/azure"
    click S3Proxy "https://github.com/versity/versitygw/tree/main/backend/s3proxy"
    click ScoutFS "https://github.com/versity/versitygw/tree/main/backend/scoutfs"
    click Kafka "https://github.com/versity/versitygw/blob/main/s3event/kafka.go"
    click NATS "https://github.com/versity/versitygw/blob/main/s3event/nats.go"
    click Webhook "https://github.com/versity/versitygw/blob/main/s3event/webhook.go"
    click DStatsD "https://github.com/versity/versitygw/blob/main/metrics/dogstats.go"
    click StatsD "https://github.com/versity/versitygw/blob/main/metrics/statsd.go"
```
