TradAI Final Architecture - Canonical Configuration¶

Version: 9.3.0 | Date: 2026-03-28 | Status: CURRENT

TL;DR: Single source of truth for all infrastructure configuration. Defines VPC CIDRs, service specs (CPU/memory/ports), DynamoDB tables, S3 buckets, Lambda configs, and environment-specific overrides. All values in infra/shared/tradai_infra_shared/config.py.

Purpose¶

This document mirrors infra/shared/tradai_infra_shared/config.py, which is the actual source of truth deployed by Pulumi. Update config.py first, then update this document to match.

graph TD
    B["infra/shared/config.py<br/><b>Source of Truth (code)</b>"] --> A["10-CANONICAL-CONFIG.md<br/><b>Human-readable mirror</b>"]
    B --> F["persistent stack"]
    B --> G["foundation stack"]
    B --> H["compute stack"]
    B --> I["edge stack"]
    A -.->|"read by"| C["Service Environment Variables<br/>ECS task definitions"]
    A -.->|"read by"| D["Lambda Configuration<br/>Memory, timeout, VPC"]
    A -.->|"read by"| E["Security Configuration<br/>SGs, NACLs, WAF, Cognito"]

    style B fill:#d32f2f,color:#fff
    style A fill:#1565c0,color:#fff

1. Network Configuration¶

1.1 VPC¶

1.2 Subnets¶

1.3 Route Tables¶

1.4 NAT Instance High Availability¶

Cost-effective NAT Instance with automatic failover (~$32/month savings vs NAT Gateway).

User Data Configuration: - IP forwarding enabled (net.ipv4.ip_forward = 1) - NAT masquerading via iptables - Automatic EIP association - Source/destination check disabled

Failover Flow: 1. ASG detects unhealthy instance (EC2 health check) 2. ASG terminates failed instance and launches replacement 3. ASG Lifecycle Hook triggers EventBridge rule 4. Lambda function tradai-update-nat-routes invoked 5. Lambda waits for instance running state 6. Lambda updates private route table (0.0.0.0/0 -> new instance) 7. Lambda completes lifecycle action 8. Traffic resumes (~2-3 minutes failover time)

IAM Permissions: - NAT Instance Role: ec2:AssociateAddress, ec2:ModifyInstanceAttribute - Lambda Role: ec2:CreateRoute, ec2:ReplaceRoute, autoscaling:CompleteLifecycleAction

2. Service Configuration¶

2.1 Service Ports¶

2.2 ECS Task Definitions¶

2.3 Service Discovery¶

2.4 Backtest Execution Modes (v9.2)¶

SQS Consumer Lambda Environment:

2.5 Strategy Container Environment Variables¶

Required (Minimal Bootstrap):

Note (Issue 10 Fix): Documentation previously used STRATEGY_NAME and STRATEGY_STAGE. The actual env vars are STRATEGY and STRATEGY_ID. Stage is determined by deployment config.

Optional (Infrastructure):

3. Storage Configuration¶

3.1 S3 Buckets¶

3.2 DynamoDB Tables¶

All 12 tables use PAY_PER_REQUEST billing, server-side encryption, and point-in-time recovery (except idempotency). Prod tables have deletion protection enabled.

Source code: infra/shared/tradai_infra_shared/config.py (DYNAMODB_TABLES dict) and infra/persistent/modules/dynamodb.py (DynamoDbTables class).

3.3 RDS Configuration¶

4. Security Configuration¶

4.1 Security Groups¶

ALB Security Group (tradai-alb-sg)¶

ECS Security Group (tradai-ecs-sg)¶

Lambda Security Group (tradai-lambda-sg)¶

RDS Security Group (tradai-rds-sg)¶

NAT Security Group (tradai-nat-sg)¶

Note: NAT SG currently allows TCP only. DNS (port 53) and NTP (port 123) use UDP. If private subnet workloads need direct DNS resolution or NTP through NAT (rather than via VPC-provided DNS), UDP rules for ports 53 and 123 should be added to both ingress and egress. Currently VPC DNS handles resolution so this is not a blocker, but should be added if custom DNS or NTP is required.

4.2 Cognito Configuration¶

4.3 WAF Configuration¶

5. API Gateway Configuration¶

5.1 Routes¶

5.2 Throttling¶

6. SQS Configuration¶

6.1 Backtest Queue¶

6.2 Dead Letter Queue¶

7. Lambda Functions¶

8. Secrets Manager¶

9. Naming Conventions¶

9.1 Resource Naming Pattern¶

{project}-{component}-{environment}[-{suffix}]

Examples:
- tradai-backend-api-prod
- tradai-vpc-dev
- tradai-backtest-queue-staging.fifo

9.2 Tag Requirements¶

All resources MUST have these tags:

10. Environment Differences¶

11. Validation Checklist¶

Before deployment, verify:

• All subnet CIDRs match this document
• All service ports match this document
• All S3 bucket names follow the pattern
• Security groups reference correct CIDRs
• All 12 DynamoDB tables match Section 3.2 (names, keys, GSIs, TTL)
• All resources have required tags
• Secrets exist in Secrets Manager
• SSL enforcement enabled on RDS

Document Control: - This document mirrors infra/shared/tradai_infra_shared/config.py which is the actual source of truth. Update config.py first, then update this document. - Changes require review and version increment - When this document conflicts with config.py, config.py takes precedence

Changelog¶

Dependencies¶