| name | architecture |
| description | References Serverless OpenClaw architecture. Covers network design, CDK stack structure, DynamoDB data model, API protocols, and container design. |
| allowed-tools | Read, Glob, Grep |
Architecture Reference
Design Documents
Core Architecture Principles
- Cost minimization: No NAT Gateway, no ALB, no Interface Endpoints
- Serverless-first: Lambda (events), Fargate Spot (long-running), DynamoDB (PAY_PER_REQUEST)
- Single responsibility: 7 separate Lambdas, 9 separate CDK stacks
- Layer separation: API Gateway → Lambda → Bridge → OpenClaw Gateway
- Protocol translation: Lambda(HTTP) ↔ Bridge ↔ OpenClaw Gateway(JSON-RPC 2.0 WebSocket)
AGENT_RUNTIME Feature Flag
Controls which agent backend handles requests:
| Value | Behavior |
|---|
fargate | Route all agent requests to Fargate container (Phase 1 mode) |
lambda | Route all agent requests to Lambda agent (Phase 2 mode) |
both | Smart routing via classifyRoute(): reuse running Fargate, honor /heavy//fargate hints, default to Lambda, fallback to Fargate on Lambda failure |
See architecture.md §12 for full Lambda architecture details and smart routing rules.
Lambda Data Flow (Phase 2)
Client → API Gateway (WS/REST) → Gateway Lambda → Lambda Agent Function
→ runEmbeddedPiAgent()
→ OpenClaw in-process
CDK Stacks (9 total)
SecretsStack + NetworkStack → StorageStack → {AuthStack, ComputeStack} → ApiStack → WebStack + MonitoringStack + LambdaAgentStack
