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