# shuttle-hq/shuttle-examples architecture

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

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

## Overview

Step 1. Identify the Project Type and Purpose:
- Project type: A multi-example repository showcasing “Hello, world!” applications and more complex fullstack templates.
- Purpose: To illustrate how different Rust frameworks (like Actix, Axum, Rocket, Salvo, etc.) and even non-web examples (like Bevy, a game framework or custom resources) integrate with Shuttle. This repository serves as a learning and reference resource for deploying diverse application types on Shuttle.

Step 2. Analyze the File Structure:
- The top level separates examples by framework and application type – for example, directories named “actix-web”, “axum”, “rocket”, “bevy”, “tide”, etc.
- Within these directories, you often see structure common to web apps, such as:
– backend and sometimes frontend folders, which indicate the separation between server-side logic and client assets.
– configuration files like Cargo.toml, Shuttle.toml, Secrets.toml or migration SQL files that indicate project dependencies, deployment configurations, and database setups.
- Additional directories like “.github”, “_benchmarks”, “_scripts” indicate CI/CD pipelines and performance testing features that might also be components in a complete deployment lifecycle.

Step 3. Examine README Insights:
- The README outlines how to clone, run locally, and deploy an example using Shuttle. This highlights the integration with Shuttle’s CLI and resources, suggesting that the core architectural element is Shuttle’s deployment platform.
- Notice that the examples vary from simple “hello-world” apps to more fullstack templates with separate UI and API backend components.

a. Main Components:
– Shuttle Deployment Platform: Central orchestrator and runtime environment.
– Application Layers within examples:
- Frontend (for fullstack templates or apps with UI): Highlight separate assets, configurations, and static files.
- Backend/API Servers: The actual Rust executables that serve HTTP requests.
– Databases & Migrations: For examples that include SQL migrations (e.g., Postgres examples) or resource configurations.
– CI/CD Components: Represent the integration with GitHub Actions (ci.yml) and other deployment scripts.

b. Relationships and Interactions:
– In applications that are fullstack (such as in “fullstack-templates/saas”), indicate the connection between the frontend UI and the backend API.
– Include data flow between backend components and their associated databases (or migration management).
– Represent the CI/CD pipeline as a separate process that feeds into the build and deploy cycle.

c. Important Architectural Patterns/Design Principles:
– Separation of Concerns: Distinguish between frontend and backend especially in fullstack templates.
– Modular Design: Each framework-specific example is a self-contained module with its own configuration and deployment settings (using Shuttle.toml, for instance).
– Extensibility: Indicate where example apps can be modified or extended—such as plugging in different authentication methods or adding resource dependencies.
– Consistent Deployability: All examples share a common deployment interface via Shuttle’s CLI.

d. Relevant Technologies, Frameworks, and Libraries:
– Rust package management (Cargo.toml).
– Various web frameworks: Actix, Axum, Rocket, Salvo, Tide, etc.
– Frontend tools in some examples (e.g., Vite, Tailwind CSS, ESLint for React-based frontends).
– External resource configurations (Secrets.toml, Shuttle.toml) that integrate the apps into Shuttle’s cloud ecosystem.
– CI/CD and benchmarking scripts present in .github and _benchmarks folders.

- Full-stack examples: Clearly demarcate frontend and backend components. Use separate clusters or containers to represent UI, API server, and database interactions.
- Open-source tool examples: Focus on the core logic encapsulated in single binaries, while showing how configuration files (like Shuttle.toml) allow integration with the deployment platform.
- Deployment specifics: Since these are examples for Shuttle, ensure that the Shuttle platform (and its CLI) is visually distinct and connected to each application, representing the deployment process.

- Clear, descriptive labels for each component (e.g., “Axum Hello World Backend”, “Fullstack SaaS Frontend”, “Shuttle Deployment Platform”).

Final Advice:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Components
    subgraph "CI/CD Components"
        CI1["GitHub_Actions_Workflow"]:::cicd
        CI2["Benchmarking_Scripts"]:::cicd
        CI3["CI_&_Deployment_Scripts"]:::cicd
    end

    %% Shuttle Deployment Platform
    SDP["Shuttle Deployment Platform"]:::platform

    %% Example Applications Cluster
    subgraph "Example Applications"
        %% Actix-Web Example
        subgraph "Actix-Web Example"
            A_conf["Shuttle.toml"]:::config
            A_backend["Backend Server"]:::backend
            A_frontend["Frontend Assets"]:::frontend
            subgraph "Databases"
                A_DB["Actix_DB_(Postgres)"]:::database
            end
            A_conf --- A_backend
            A_conf --- A_frontend
            A_frontend -->|"calls"| A_backend
            A_backend -->|"connects"| A_DB
        end

        %% Axum Example
        subgraph "Axum Example"
            Ax_conf["Shuttle.toml"]:::config
            Ax_backend["Backend Server"]:::backend
            Ax_frontend["Frontend Assets"]:::frontend
            Ax_conf --- Ax_backend
            Ax_conf --- Ax_frontend
        end

        %% Rocket Example
        subgraph "Rocket Example"
            R_conf["Shuttle.toml"]:::config
            R_backend["Backend Server"]:::backend
            subgraph "Databases"
                R_DB["Rocket_DB"]:::database
            end
            R_conf --- R_backend
            R_backend -->|"connects"| R_DB
        end

        %% Fullstack SaaS Example
        subgraph "Fullstack SaaS Example"
            FS_conf["Shuttle.toml"]:::config
            FS_backend["Backend Server"]:::backend
            FS_frontend["Frontend_UI"]:::frontend
            subgraph "Databases"
                FS_DB["Fullstack_DB"]:::database
            end
            FS_conf --- FS_backend
            FS_conf --- FS_frontend
            FS_frontend -->|"consumes"| FS_backend
            FS_backend -->|"connects"| FS_DB
        end

        %% Other Examples
        subgraph "Other Examples"
            OE["Various_Framework_Examples"]:::example
        end
    end

    %% Data Flow Relationships
    CI1 --> SDP
    CI2 --> SDP
    CI3 --> SDP
    SDP --> A_conf
    SDP --> Ax_conf
    SDP --> R_conf
    SDP --> FS_conf
    SDP --> OE

    %% Class Definitions for Colors
    classDef cicd fill:#f9e79f,stroke:#000,stroke-width:2px;
    classDef platform fill:#81ecec,stroke:#000,stroke-width:2px;
    classDef backend fill:#fab1a0,stroke:#000,stroke-width:2px;
    classDef frontend fill:#a29bfe,stroke:#000,stroke-width:2px;
    classDef database fill:#55efc4,stroke:#000,stroke-width:2px;
    classDef config fill:#ffeaa7,stroke:#000,stroke-width:2px;
    classDef example fill:#dfe6e9,stroke:#000,stroke-width:2px;

    %% Click Events for Shuttle.toml configuration files in examples
    click A_conf "https://github.com/shuttle-hq/shuttle-examples/blob/main/actix-web/clerk/Shuttle.toml"
    click Ax_conf "https://github.com/shuttle-hq/shuttle-examples/blob/main/axum/openai/Shuttle.toml"
    click R_conf "https://github.com/shuttle-hq/shuttle-examples/blob/main/rocket/dyn-templates/Shuttle.toml"
    click FS_conf "https://github.com/shuttle-hq/shuttle-examples/blob/main/fullstack-templates/saas/Shuttle.toml"

    %% Click Events for Backend Servers
    click A_backend "https://github.com/shuttle-hq/shuttle-examples/blob/main/actix-web/clerk/backend/src/main.rs"
    click Ax_backend "https://github.com/shuttle-hq/shuttle-examples/blob/main/axum/hello-world/src/main.rs"
    click R_backend "https://github.com/shuttle-hq/shuttle-examples/blob/main/rocket/hello-world/src/main.rs"
    click FS_backend "https://github.com/shuttle-hq/shuttle-examples/blob/main/fullstack-templates/saas/backend/src/main.rs"

    %% Click Events for Frontend Components
    click A_frontend "https://github.com/shuttle-hq/shuttle-examples/tree/main/actix-web/clerk/frontend"
    click Ax_frontend "https://github.com/shuttle-hq/shuttle-examples/tree/main/axum/openai/frontend"
    click FS_frontend "https://github.com/shuttle-hq/shuttle-examples/tree/main/fullstack-templates/saas/src/pages"

    %% Click Events for Databases & Migrations
    click A_DB "https://github.com/shuttle-hq/shuttle-examples/blob/main/actix-web/postgres/migrations/0001_init.sql"
    click R_DB "https://github.com/shuttle-hq/shuttle-examples/blob/main/rocket/postgres/schema.sql"
    click FS_DB "https://github.com/shuttle-hq/shuttle-examples/tree/main/fullstack-templates/saas/backend/migrations"

    %% Click Event for Other Examples
    click OE "https://github.com/shuttle-hq/shuttle-examples/tree/main/bevy"

    %% Click Events for CI/CD Components
    click CI1 "https://github.com/shuttle-hq/shuttle-examples/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/shuttle-hq/shuttle-examples/tree/main/_benchmarks"
    click CI3 "https://github.com/shuttle-hq/shuttle-examples/blob/main/_scripts/ci.sh"
```
