docs: Add Shuttle Python documentation

Author: fussybeaver

docs.json

@@ -0,0 +1,142 @@
+---
+title: "Shuttle Architecture"
+description: "Understand how Shuttle's infrastructure-from-code platform works under the hood"
+icon: "building"
+---
+
+## 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.

python/explanation/architecture.mdx

@@ -0,0 +1,167 @@
+---
+title: "Infrastructure from Code"
+description: "Deep dive into Shuttle's Infrastructure from Code philosophy and how it differs from traditional approaches"
+icon: "code"
+---
+
+## What is Infrastructure from Code?
+
+Infrastructure from Code (IfC) is Shuttle's foundational approach where infrastructure requirements are expressed directly in your application code through language-native constructs like type hints, attributes, or decorators, rather than in separate configuration files or management consoles.
+
+## The Philosophy
+
+Traditional cloud development often separates concerns:
+
+-   **Application Logic**: Your business code
+-   **Infrastructure Configuration**: YAML files, Terraform, CloudFormation
+-   **Deployment Scripts**: CI/CD pipelines, Docker configurations
+
+This separation, while architecturally sound, can introduce friction:
+
+-   Context switching between code and infrastructure definitions.
+-   Synchronization challenges between different environments.
+-   Complex dependency management.
+-   A higher barrier to entry for new developers.
+
+Shuttle's Infrastructure from Code collapses this complexity by enabling you to express infrastructure needs directly alongside where they are used in your application code.
+
+## How Shuttle's IfC Works
+
+At its core, IfC means that your application code becomes the single source of truth for both your business logic and your infrastructure requirements.
+
+### 1. Declarative Resource Requirements
+
+You declare the resources your application needs directly in your code, typically as function parameters or class members, using language-native features. Shuttle then interprets these declarations to provision the necessary cloud infrastructure.
+
+For example, you might declare a database, a storage bucket, or a secret manager entry. Shuttle understands these declarations and handles the provisioning, configuration, and injection of the actual resources into your running application.
+
+### 2. Automatic Lifecycle Management
+
+When you deploy your application with Shuttle:
+
+-   **Provisioning**: Required resources are automatically created on first deployment.
+-   **Persistence**: Resources like databases or storage buckets persist across deployments, maintaining their state.
+-   **Management**: Shuttle manages updates, backups, and scaling of these resources where applicable.
+-   **Cleanup**: Resources are automatically torn down when they are no longer declared in your code, preventing orphaned infrastructure.
+
+## IfC vs. Traditional Infrastructure Provisioning
+
+To illustrate the difference, consider provisioning a PostgreSQL database for your application:
+
+### Traditional Approach Example
+
+With traditional methods, you'd define your infrastructure in separate files and manage environment variables:
+
+```yaml
+# docker-compose.yml or similar IaC tool
+services:
+  database:
+    image: postgres:13
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: password
+
+  app:
+    build: .
+    depends_on:
+      - database
+    environment:
+      DATABASE_URL: postgres://user:password@database:5432/myapp
+```
+
+And your application code would retrieve the connection string from environment variables:
+
+```python
+# Your app code
+import os
+import psycopg
+from psycopg_pool import ConnectionPool
+
+DATABASE_URL = os.environ.get("DATABASE_URL")
+if not DATABASE_URL:
+    raise ValueError("DATABASE_URL environment variable is not set")
+
+pool = ConnectionPool(DATABASE_URL)
+# ... use pool to interact with the database ...
+```
+
+This approach requires manual synchronization between the infrastructure definition and the application's environment variable consumption.
+
+### Infrastructure from Code in Python Example
+
+With Shuttle's IfC in Python, the database requirement is expressed directly in your application code:
+
+```python
+from typing import Annotated
+
+import shuttle_runtime
+import shuttle_task
+from shuttle_aws.s3 import Bucket, BucketOptions, AllowWrite
+from shuttle_aws.rds import RdsPostgres, RdsPostgresOptions
+from shuttle_runtime import Secrets
+
+@shuttle_task.cron(schedule="0 3 * * ? *")
+async def run(
+    # Dedicated AWS RDS Postgres with custom options
+    production_db: Annotated[
+        RdsPostgres,
+        RdsPostgresOptions(
+            database_name="prod_metrics",
+            allocated_storage_gb=20,
+        ),
+    ],
+    # Dedicated AWS S3 Bucket with write permissions
+    data_bucket: Annotated[Bucket,
+        BucketOptions(
+            bucket_name="my-app-data-bucket-unique", # Must be globally unique
+            policies=[
+                AllowWrite(
+                    account_id="123456789012",  # Example AWS account ID
+                    role_name="MyExternalServiceRole",
+                ),
+            ],
+        ),
+    ],
+    # A secret automatically managed by Shuttle
+    secrets: Secrets,
+):
+    # All resources are ready to use as function arguments
+    print(f"Connected to production DB host: {production_db.get_connection().dsn}")
+    print(f"Data bucket name: {data_bucket.options.bucket_name}")
+    print(f"Secrets available: {secrets.get('MY_SECRET')}")
+```
+
+In this Python example, `RdsPostgres` and `Bucket` are type hints that tell Shuttle what resources are needed. The `Annotated` type allows for additional configuration (e.g., `RdsPostgresOptions`). Shuttle automatically provisions these resources and injects fully configured, ready-to-use instances into your function at runtime.
+
+## Developer Experience & Efficiency
+
+### Unified Codebase for App & Infra
+
+Infrastructure requirements are defined directly within your application code using type hints and decorators. This creates a single source of truth, eliminating the need for separate configuration files (like Terraform or CloudFormation) and reducing context switching.
+
+-   **Version Control**: Since infrastructure is code, all changes to your application and its underlying resources are tracked together in version control, simplifying collaboration, code reviews, and rollbacks.
+
+With commands like `shuttle deploy`, `shuttle logs`, and `shuttle destroy`, the platform automatically provisions, updates, and tears down resources. The CLI provides immediate, human-readable feedback (diffs) on planned infrastructure changes, ensuring consistency and reproducibility across environments.
+
+### Enhanced Local Development
+
+## Limitations and Considerations
+
+### When IfC Might Not Be Ideal and Working Within Constraints
+
+Infrastructure from Code may not be ideal in scenarios such as complex multi-service architectures not fully managed by Shuttle, strict compliance requirements that demand external auditing of infrastructure, legacy system integration, or highly diverse multi-language environments where a common IaC tool might be preferred. In these cases, consider:
+
+-   **Hybrid Approaches**: Integrating Shuttle-managed parts with external infrastructure definitions managed by traditional IaC tools.
+-   **Custom Resources**: For complex infrastructure needs not directly supported by Shuttle's built-in types, you might define them externally and integrate them into your Shuttle project.
+-   **Traditional IaC**: Combining Shuttle with traditional Infrastructure as Code tools for legacy components or highly specialized requirements that fall outside Shuttle's immediate scope.
+
+## The Future of Infrastructure from Code
+
+As AI and machine learning technologies advance, they are poised to revolutionize Infrastructure from Code by making it even more approachable and efficient. AI tools combined with succinct syntax will lower the barrier to entry for developers, making it easier to manage infrastructure through code.
+
+-   **AI-Enhanced Tooling**: AI will enable more intuitive interaction with infrastructure, allowing developers to focus on application logic rather than complex configurations.
+-   **Streamlined Orchestration**: With AI-driven command-line tools, orchestrating infrastructure provisioning will become more streamlined, reducing the need for verbose commands.
+-   **Short Context Prompting**: AI will enhance the accuracy of infrastructure management tasks by understanding short context prompts, improving over verbose and error-prone infrastructure tools.
+
+Understanding Infrastructure from Code helps you leverage Shuttle's full potential and design applications that are both powerful and maintainable.

python/explanation/infrastructure-from-code.mdx

@@ -0,0 +1,48 @@
+---
+title: "CLI Installation"
+description: "How to install the Python-based Shuttle Command Line Interface (CLI) using uv"
+icon: "download"
+---
+
+## <span style={{ fontWeight: 600 }}>Using Shuttle within your projects</span>
+
+<span style={{ fontSize: '1.1em', fontWeight: 500 }}>
+For managing dependencies and running Shuttle commands within your projects, it is recommended to use `uv` directly.
+</span>
+
+1.  <b>Create a Virtual Environment</b>
+
+    Navigate to your project directory and create a virtual environment with `uv`.
+
+        <CodeBlock language="bash" expanded>
+        uv venv
+        source .venv/bin/activate
+        </CodeBlock>
+
+2.  <b>Add Shuttle Dependency</b>
+
+    Add the `shuttle` package to your project's dependencies.
+
+        <CodeBlock language="bash" expanded>
+        uv init
+        uv add shuttle-python
+        </CodeBlock>
+
+3.  <b>Run Shuttle Commands</b>
+
+    Execute Shuttle commands using `uv run -m shuttle` to ensure they run within your project's isolated environment.
+
+        <CodeBlock language="bash" expanded>
+        uv run -m shuttle deploy
+        uv run -m shuttle logs
+        uv run -m shuttle local
+        </CodeBlock>
+
+    Alternatively, if you are activated in your virtual environment, you can use the `shuttle` script.
+
+        <CodeBlock language="bash" expanded>
+        shuttle deploy
+        shuttle logs
+        shuttle local
+        </CodeBlock>
+