> For the complete documentation index, see [llms.txt](https://shuttle-1.gitbook.io/shuttle-cobra/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shuttle-1.gitbook.io/shuttle-cobra/explanation/shuttle-architecture.md).

# Shuttle Architecture

### 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

```python
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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://shuttle-1.gitbook.io/shuttle-cobra/explanation/shuttle-architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.