# shuttle-hq/shuttle architecture

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

- Interactive diagram: https://gitdiagram.com/shuttle-hq/shuttle
- Repository: https://github.com/shuttle-hq/shuttle

## Overview

##### Main Components Identification

The system consists of several key services that should be represented as primary components:

a) Core Services:
- Gateway (API Gateway/Router)
- Auth Service (Authentication/Authorization)
- Deployer (Deployment Management)
- Provisioner (Resource Provisioning)
- Runtime (Application Execution)
- Logger (Logging Service)
- Resource Recorder (Resource Management)

b) Client-facing Components:
- cargo-shuttle (CLI Tool)
- API Client
- Admin Interface

c) Resource Providers:
- AWS RDS
- OpenAI
- Qdrant
- Shared Databases (Postgres/MongoDB)
- Turso
- OpenDAL

##### Relationship Structure

a) External User Interactions:
**User -> cargo-shuttle (CLI) -> Gateway**
**User -> HTTP Requests -> Gateway**

b) Internal Service Communications:
**Gateway -> Auth Service (Authentication)**
**Gateway -> Deployer (Deployment Management)**
**Deployer -> Provisioner (Resource Creation)**
**Deployer -> Runtime (Application Execution)**
**Runtime -> Resource Recorder (Resource Tracking)**
**All Services -> Logger (Logging)**

##### Design Elements

Use the following visual elements:

- Rectangles: Main services and components
- Hexagons: External resources (databases, cloud services)
- Blue: Core services
- Green: External resources
- Orange: Client-facing components
- Gray: Infrastructure components

##### Key Architectural Patterns to Highlight

- Microservices Architecture: Show clear separation between services
- API Gateway Pattern: Emphasize the gateway's central role
- Resource Provisioning Pipeline: Show the flow from request to resource creation
- Authentication Flow: Demonstrate how auth permeates the system

##### Additional Details

- Database connections (show PostgreSQL instances)
- Message queues for async operations
- Monitoring and logging flows
- Load balancers where applicable
- Security boundaries and zones

##### Deployment Context

A separate section or layer showing:
- Production environment
- Development environment
- CI/CD pipeline integration
- Container orchestration

##### Documentation Integration

References to:
- API documentation
- Service documentation
- Configuration requirements
- Security protocols
- Scaling policies

Remember to maintain a balance between showing enough detail to understand the system's complexity while keeping it clear and digestible for the audience.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles
    classDef client fill:#FFA500,stroke:#000,stroke-width:2px
    classDef core fill:#4169E1,stroke:#000,stroke-width:2px
    classDef resource fill:#228B22,stroke:#000,stroke-width:2px
    classDef support fill:#800080,stroke:#000,stroke-width:2px
    
    %% Client Layer
    User(["👤 User/Developer"])
    CLI["cargo-shuttle CLI"]:::client
    ApiClient["API Client"]:::client
    Admin["Admin Interface"]:::client
    
    %% Core Services
    Gateway["API Gateway"]:::core
    Auth["Auth Service"]:::core
    Deployer["Deployer"]:::core
    Provisioner["Provisioner"]:::core
    Runtime["Runtime"]:::core
    
    %% Support Services
    Logger["Logger"]:::support
    ResourceRecorder["Resource Recorder"]:::support
    
    %% Resource Providers
    subgraph Resources["Resource Providers"]
        direction TB
        AWSRDS["AWS RDS"]:::resource
        OpenAI["OpenAI"]:::resource
        Qdrant["Qdrant"]:::resource
        SharedDB["Shared Databases"]:::resource
        Turso["Turso"]:::resource
        OpenDAL["OpenDAL"]:::resource
    end
    
    %% Relationships
    User --> CLI & ApiClient & Admin
    CLI & ApiClient & Admin --> Gateway
    
    Gateway --> Auth
    Gateway --> Deployer
    Gateway --> ResourceRecorder
    
    Auth --> Deployer
    Auth --> ResourceRecorder
    
    Deployer --> Provisioner
    Deployer --> Logger
    
    Provisioner --> Runtime
    Provisioner --> ResourceRecorder
    
    Runtime --> Resources
    Runtime --> Logger
    
    ResourceRecorder --> Logger
    
    %% Click Events
    click Gateway "https://github.com/shuttle-hq/shuttle/blob/main/gateway/src/main.rs"
    click Auth "https://github.com/shuttle-hq/shuttle/blob/main/auth/src/main.rs"
    click Deployer "https://github.com/shuttle-hq/shuttle/blob/main/deployer/src/main.rs"
    click Provisioner "https://github.com/shuttle-hq/shuttle/blob/main/provisioner/src/main.rs"
    click Runtime "https://github.com/shuttle-hq/shuttle/blob/main/runtime/src/main.rs"
    click Logger "https://github.com/shuttle-hq/shuttle/blob/main/logger/src/main.rs"
    click ResourceRecorder "https://github.com/shuttle-hq/shuttle/blob/main/resource-recorder/src/main.rs"
    click CLI "https://github.com/shuttle-hq/shuttle/blob/main/cargo-shuttle/src/bin/cargo-shuttle.rs"
    click ApiClient "https://github.com/shuttle-hq/shuttle/blob/main/api-client/src/lib.rs"
    click Admin "https://github.com/shuttle-hq/shuttle/blob/main/admin/src/main.rs"
    click AWSRDS "https://github.com/shuttle-hq/shuttle/blob/main/resources/aws-rds/src/lib.rs"
    click OpenAI "https://github.com/shuttle-hq/shuttle/blob/main/resources/openai/src/lib.rs"
    click Qdrant "https://github.com/shuttle-hq/shuttle/blob/main/resources/qdrant/src/lib.rs"
    click SharedDB "https://github.com/shuttle-hq/shuttle/blob/main/resources/shared-db/src/lib.rs"
    click Turso "https://github.com/shuttle-hq/shuttle/blob/main/resources/turso/src/lib.rs"
    click OpenDAL "https://github.com/shuttle-hq/shuttle/blob/main/resources/opendal/src/lib.rs"
    
    %% Legend
    subgraph Legend
        direction TB
        Client["Client Component"]:::client
        CoreService["Core Service"]:::core
        ResourceProvider["Resource Provider"]:::resource
        SupportService["Support Service"]:::support
    end
```
