Shuttle Architecture

Understand how Shuttle's infrastructure-from-code platform works under the hood

Overview

Shuttle is designed around a fundamental principle: Infrastructure from Code. Unlike traditional platforms where you configure infrastructure separately from your application code, Shuttle provisions and manages infrastructure directly from your Python code using type hints and decorators.

Core Architecture

The Shuttle Runtime

At the heart of Shuttle is how your application's entrypoint is handled, typically using shuttle_runtime.main(your_function) or a decorated function like @shuttle_task.cron. This approach:

• Analyzes your code to understand what resources you need

• Provisions infrastructure automatically based on your type hints and resource options

• Handles deployment lifecycle including startup, shutdown, and health checks

• Manages resource connections and provides them to your application

import shuttle_runtime
import shuttle_task
from shuttle_aws.s3 import Bucket, BucketOptions
from shuttle_aws.rds import RdsPostgres, RdsPostgresOptions
from typing import Annotated

@shuttle_task.cron(schedule="0 3 * * ? *")
async def run(
    bucket: Bucket: Annotated[
      Bucket, BucketOptions(bucket_name="my-bucket", policies=[])
    ],
    db: Annotated[RdsPostgres, RdsPostgresOptions()],
):
    # Your app code here - infrastructure is ready
    pass

Resource Provisioning System

Shuttle's resource system works through a combination of:

1. Code Analysis: Shuttle scans your code for type hints and resource options

2. Infrastructure Planning: The platform determines what resources to provision

3. Automatic Provisioning: Resources are created and configured

4. Runtime Injection: Live connections are provided to your application

This approach eliminates the need for:

• Manual infrastructure configuration

• Environment-specific connection strings

• Complex deployment scripts

• Infrastructure-as-code templates

Deployment Pipeline

When you run shuttle deploy, here's what happens:

1. Code Archive: Your project is bundled and uploaded

2. Build Phase: Dependencies are installed and code is prepared in a secure build environment

3. Resource Analysis: The runtime analyzes required resources

4. Infrastructure Provisioning: Resources are created or updated

5. Container Deployment: Your app is deployed to AWS ECS (Fargate)

6. Health Checks: The platform verifies deployment success

Isolation and Security

Each Shuttle project runs in its own:

• ECS Service: Dedicated compute isolation

• Resource Namespace: Logical separation of databases, secrets, etc.

• Network Context: Isolated networking and security groups

Design Principles

Developer Experience First

Shuttle prioritizes developer productivity by:

• Reducing boilerplate and configuration

• Providing immediate feedback during development

• Abstracting infrastructure complexity

• Maintaining familiar Python development patterns

Infrastructure Transparency

While Shuttle abstracts infrastructure management, it maintains transparency by:

• Providing clear resource information in the console

• Offering detailed deployment logs

• Supporting custom resource configurations when needed

• Maintaining compatibility with standard Python libraries and frameworks

Scalability by Design

The architecture supports growth through:

• Automatic resource scaling based on usage

• Support for custom resource configurations

• Integration with external services and databases

• Multi-region deployment capabilities (Enterprise)

Comparison with Traditional Approaches

Traditional Deployment

Code → Docker Image → Kubernetes/Docker Compose → Infrastructure Config → Deploy

Shuttle Approach

Annotated Code → shuttle deploy → Running Application

This simplified flow reduces complexity while maintaining full control over your application logic.

Resource Lifecycle

Resources in Shuttle follow a managed lifecycle:

1. Declaration: Resources are declared via type hints and decorators in your code

2. Provisioning: First deployment creates the resource

3. Persistence: Resources persist across deployments

4. Management: Resources can be managed via CLI or console

5. Cleanup: Resources are cleaned up when projects are deleted

This lifecycle ensures that your data persists while your application code evolves.

Understanding the Platform Benefits

Shuttle's architecture provides several key advantages:

• Faster Development: No infrastructure setup time

• Reduced Complexity: Infrastructure and application code in one place

• Better Reliability: Managed infrastructure with automatic scaling

• Cost Efficiency: Pay only for what you use, automatic optimization

• Security: Built-in best practices and managed updates

Understanding these architectural principles helps you make the most of Shuttle's capabilities and design applications that leverage the platform's strengths.