How shuttle-hq/shuttle works
Main Components Identification
The system consists of several key services that should be represented as primary components:
a) Core Services:
• Gateway (API Gateway/Router)
• Auth Service (Authentication/Authorization)
• Deployer (Deployment Management)
• Provisioner (Resource Provisioning)
• Runtime (Application Execution)
• Logger (Logging Service)
• Resource Recorder (Resource Management)
b) Client-facing Components:
• cargo-shuttle (CLI Tool)
• API Client
• Admin Interface
c) Resource Providers:
• AWS RDS
• OpenAI
• Qdrant
• Shared Databases (Postgres/MongoDB)
• Turso
• OpenDAL
Relationship Structure
a) External User Interactions:
User -> cargo-shuttle (CLI) -> Gateway
User -> HTTP Requests -> Gateway
b) Internal Service Communications:
Gateway -> Auth Service (Authentication)
Gateway -> Deployer (Deployment Management)
Deployer -> Provisioner (Resource Creation)
Deployer -> Runtime (Application Execution)
Runtime -> Resource Recorder (Resource Tracking)
All Services -> Logger (Logging)
Design Elements
Use the following visual elements:
• Rectangles: Main services and components
• Hexagons: External resources (databases, cloud services)
• Blue: Core services
• Green: External resources
• Orange: Client-facing components
• Gray: Infrastructure components
Key Architectural Patterns to Highlight
• Microservices Architecture: Show clear separation between services
• API Gateway Pattern: Emphasize the gateway's central role
• Resource Provisioning Pipeline: Show the flow from request to resource creation
• Authentication Flow: Demonstrate how auth permeates the system
Additional Details
• Database connections (show PostgreSQL instances)
• Message queues for async operations
• Monitoring and logging flows
• Load balancers where applicable
• Security boundaries and zones
Deployment Context
A separate section or layer showing:
• Production environment
• Development environment
• CI/CD pipeline integration
• Container orchestration
Documentation Integration
References to:
• API documentation
• Service documentation
• Configuration requirements
• Security protocols
• Scaling policies
Remember to maintain a balance between showing enough detail to understand the system's complexity while keeping it clear and digestible for the audience.