TradAI Infrastructure as Code (Pulumi)¶

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

TL;DR: 4-stack Pulumi architecture in eu-central-1. Stacks are layered by lifecycle: persistent (data-bearing, never destroyed) -> foundation (VPC, RDS) -> compute (ECS, Lambda, Step Functions) -> edge (API Gateway, WAF, CloudWatch). All config centralized in infra/shared/tradai_infra_shared/config.py.

1. Architecture Overview¶

TradAI uses a 4-stack Pulumi architecture deployed in eu-central-1. Stacks are layered by lifecycle and dependency: persistent data is separated from ephemeral compute, which is separated from edge routing and monitoring.

Stack Dependency Flow¶

graph LR
    A["persistent<br/><small>S3, DynamoDB, ECR<br/>Cognito, CodeArtifact</small>"] --> B["foundation<br/><small>VPC, Subnets, RDS<br/>SQS, SNS, NAT</small>"]
    B --> C["compute<br/><small>IAM, ALB, ECS<br/>Lambda, Step Functions</small>"]
    C --> D["edge<br/><small>API Gateway, WAF<br/>CloudWatch, Alarms</small>"]

    style A fill:#2d6a4f,color:#fff
    style B fill:#40916c,color:#fff
    style C fill:#52b788,color:#000
    style D fill:#95d5b2,color:#000

Why 4 Stacks?¶

Cross-Stack Communication¶

Stacks share outputs via Pulumi StackReference. Each downstream stack declares references to its upstream stacks and reads exported values:

# Example from compute/__main__.py
persistent = pulumi.StackReference(f"{org}/tradai-persistent/{pulumi.get_stack()}")
foundation = pulumi.StackReference(f"{org}/tradai-foundation/{pulumi.get_stack()}")

vpc_id = foundation.get_output("vpc_id")
ecr_repository_urls = persistent.get_output("ecr_repository_urls")

Shared Library¶

All four stacks depend on infra/shared/tradai_infra_shared/, a local Python package providing: - config.py -- Single source of truth for all resource names, sizes, and feature flags - core/ -- Reusable builder patterns (PolicyBuilder, SecurityRuleBuilder, etc.) - testing.py -- PulumiMocks and test fixtures shared across stack test suites

2. Project Structure¶

infra/
├── persistent/                    # Stack 1: data-bearing resources
│   ├── __main__.py
│   └── modules/
│       ├── s3.py                  # 5 S3 buckets
│       ├── dynamodb.py            # 12 DynamoDB tables
│       ├── ecr.py                 # 24 ECR repositories (6 service + 18 Lambda)
│       ├── cognito.py             # User pool, app clients, M2M client
│       ├── codeartifact.py        # Python package registry
│       ├── cloudtrail.py          # Audit logging
│       └── pulumi_backend.py      # Self-hosted Pulumi state in S3
│
├── foundation/                    # Stack 2: networking + databases
│   ├── __main__.py
│   └── modules/
│       ├── vpc.py                 # VPC, subnets (public/private/database), IGW, routes
│       ├── security_groups.py     # ALB, ECS, Lambda, RDS, NAT, endpoint SGs
│       ├── nacl.py                # Network ACLs per subnet tier
│       ├── nat_instance.py        # t4g.nano NAT instance (~$3/month)
│       ├── vpc_endpoints.py       # S3, DynamoDB, ECR, CloudWatch, STS endpoints
│       ├── vpc_flow_logs.py       # VPC traffic logging
│       ├── rds.py                 # PostgreSQL 15 (MLflow metadata store)
│       ├── sqs.py                 # Backtest queue + DLQ
│       ├── sns.py                 # Alerts + registration topics
│       └── secret_rotation.py     # RDS credential rotation
│
├── compute/                       # Stack 3: compute resources
│   ├── __main__.py
│   ├── asl_templates/             # Step Functions workflow templates
│   │   ├── backtest_workflow.json.j2
│   │   └── retraining_workflow.json.j2
│   └── modules/
│       ├── iam.py                 # Execution/task/CLI-CI/consolidated roles
│       ├── alb.py                 # Application Load Balancer + target groups
│       ├── ecs.py                 # ECS cluster + strategy task definition
│       ├── ecs_services.py        # 7 ECS services + Service Discovery
│       ├── lambda_funcs.py        # 18 Lambda functions + EventBridge schedules
│       ├── step_functions.py      # Backtest + retraining workflows
│       ├── ec2_consolidated.py    # Single EC2 instance for dev/staging
│       └── ec2_userdata.py        # Userdata script generation
│
├── edge/                          # Stack 4: routing + monitoring
│   ├── __main__.py
│   └── modules/
│       ├── api_gateway.py         # HTTP API, VPC Link, JWT auth, SQS integration
│       ├── waf.py                 # Rate limiting, geo-blocking, managed rule groups
│       ├── cloudwatch_alarms.py   # Composite alarm, RDS/Lambda/StepFunctions alarms
│       └── cloudwatch_dashboard.py # Operational dashboard
│
├── shared/                        # Shared library (all stacks depend on this)
│   └── tradai_infra_shared/
│       ├── config.py              # All configuration values
│       ├── testing.py             # PulumiMocks for unit tests
│       └── core/
│           ├── policy_builder.py
│           ├── security_rule_builder.py
│           ├── asl_loader.py
│           ├── environment_builder.py
│           ├── ami_lookup.py
│           └── shell_template_env.py
│
├── ami/                           # Packer AMI for consolidated EC2
│   ├── tradai-consolidated.pkr.hcl
│   └── files/
│
├── .env                           # AWS_PROFILE, PULUMI_CONFIG_PASSPHRASE, S3_PULUMI_BACKEND_URL
├── README.md
├── TEARDOWN.md
└── pulumi-ci.sh

3. Shared Configuration¶

All resource names, sizes, feature flags, and routing rules are centralized in a single file: infra/shared/tradai_infra_shared/config.py

This is the canonical source of truth. No stack module hardcodes resource names -- everything is imported from config.

Configuration Groups¶

Naming Conventions¶

All resource names follow the pattern tradai-{component}-{ENVIRONMENT}. The config module provides helper functions to generate these consistently:

Environment-Specific Behavior¶

The ENVIRONMENT variable comes from pulumi.get_stack() (the stack name is the environment). Several config values change by environment:

4. Stack: Persistent¶

Purpose: Data-bearing resources that survive dev-cycle teardowns. Destroying this stack means losing all market data, backtest results, container images, and user accounts.

Deploy: just infra-up-persistent Entry point: infra/persistent/__main__.py

Resources¶

Design Decisions¶

• Separate from foundation: VPC teardown should never risk deleting S3 or DynamoDB data.
• ECR here, not compute: Images must exist before compute stack can create task definitions. just lambda-bootstrap pushes images to ECR between persistent and compute deployments.
• Cognito here, not edge: User pool is data-bearing (user accounts persist).

5. Stack: Foundation¶

Purpose: Networking infrastructure and VPC-bound databases. Rarely destroyed because VPC changes cascade to every resource with a subnet or security group dependency.

Deploy: just infra-up-foundation (after persistent) Entry point: infra/foundation/__main__.py

Resources¶

Design Decisions¶

• RDS in foundation, not persistent: RDS requires VPC subnet groups. Placing it with networking avoids circular cross-stack dependencies.
• SQS/SNS in foundation: Messaging resources are VPC-adjacent and consumed by both compute and edge stacks.
• NAT instance over NAT Gateway: t4g.nano costs ~$3/month vs ~$32/month for NAT Gateway. Acceptable for dev/staging traffic volumes.

6. Stack: Compute¶

Purpose: All compute workloads -- the most frequently updated stack. Contains IAM roles, ECS cluster and services, Lambda functions, Step Functions workflows, ALB, and the optional consolidated EC2 instance.

Deploy: just infra-up-compute (after foundation + Lambda images pushed to ECR) Entry point: infra/compute/__main__.py

Stack References¶

Compute reads from both upstream stacks: - persistent: ECR repo URLs, S3 bucket IDs, DynamoDB table names - foundation: VPC ID, subnet IDs, security group IDs, RDS endpoint, SQS/SNS ARNs

Resources¶

Consolidated EC2 Mode¶

In dev/staging, is_consolidated_mode() returns True. Instead of running 4 separate Fargate tasks (~$37/month), a single t3.small EC2 instance (~$15/month) runs backend-api, data-collection, mlflow, and strategy-service via Docker Compose. The instance: - Registers with ALB target groups for each service - Registers with Service Discovery for inter-service communication - Pulls images from ECR using an instance profile role - Receives per-service environment variables (S3 buckets, RDS endpoint, SQS URL, etc.)

In prod, is_consolidated_mode() returns False and services run as individual Fargate tasks for reliability and independent scaling.

Lambda Deployment Model¶

Lambda functions use container images (not ZIP). Each Lambda has a dedicated ECR repo in the persistent stack. The deployment flow is:

1. just lambda-bootstrap builds and pushes all 18 Lambda images to ECR
2. just infra-up-compute creates Lambda functions referencing those image URIs
3. Some Lambdas are "deferred" -- created after Step Functions so they can receive the workflow ARN as an environment variable

Step Functions Workflows¶

Two state machines are defined using Jinja2 ASL templates in infra/compute/asl_templates/: - backtest_workflow.json.j2 -- Orchestrates: validate strategy, run ECS task, consume results, update status - retraining_workflow.json.j2 -- Orchestrates: check if retraining needed, run training, compare models, promote

Templates are rendered at deploy time with Lambda ARNs, ECS cluster ARN, subnet IDs, and security group IDs injected as template variables.

7. Stack: Edge¶

Purpose: External-facing routing and operational monitoring. Can be redeployed independently of compute resources.

Deploy: just infra-up-edge (after compute) Entry point: infra/edge/__main__.py

Stack References¶

Edge reads from all three upstream stacks: - persistent: Cognito user pool ID, client IDs, endpoint - foundation: VPC ID, subnet IDs, ECS SG, SQS queue URL/ARN, SNS topic ARN, RDS identifier - compute: ALB DNS name, listener ARNs, Step Functions workflow names

Resources¶

Design Decisions¶

• API Gateway uses VPC Link: Routes traffic to ALB in private subnets; no public ALB needed.
• Backtest POST routes to SQS: API Gateway has native SQS integration -- the request goes directly to the backtest queue without hitting any compute resource.
• WAF not associated with HTTP API: WAFv2 cannot parse the $default stage ARN of HTTP APIs. The WebACL is created but requires REST API or ALB association to be effective.
• JWT auth via Cognito: API Gateway validates JWTs against the Cognito user pool. Health check endpoint is unauthenticated.

8. Core Patterns¶

The shared library at infra/shared/tradai_infra_shared/core/ provides reusable builder patterns that eliminate duplication across stack modules.

PolicyBuilder¶

File: infra/shared/tradai_infra_shared/core/policy_builder.py

Fluent builder for IAM policies. Provides preset methods for common permission sets (DynamoDB CRUD, S3 read/write, Secrets Manager, CloudWatch, SNS, CodeArtifact) and composes them into a single policy document. Also provides AssumeRolePolicyBuilder with factory methods like for_ecs_tasks() and for_lambda().

# Example: building a task role policy
policy = (PolicyBuilder("tradai")
    .with_dynamodb_crud()
    .with_s3_readwrite()
    .with_secrets_read()
    .with_cloudwatch_metrics()
    .build())

SecurityRuleBuilder¶

File: infra/shared/tradai_infra_shared/core/security_rule_builder.py

Fluent builder for security group rules. Provides CommonPorts with predefined port ranges for all services and PortRange for custom ranges. Methods like ingress_from_sg() and egress_https_to_internet() create rules with consistent naming and tagging.

AslTemplateLoader¶

File: infra/shared/tradai_infra_shared/core/asl_loader.py

Jinja2-based loader for Amazon States Language (ASL) workflow definitions. Renders .json.j2 templates from infra/compute/asl_templates/ with Lambda ARNs, ECS config, and subnet IDs injected as variables. Validates rendered output is valid JSON.

EnvironmentBuilder¶

File: infra/shared/tradai_infra_shared/core/environment_builder.py

Fluent builder for container environment variables that handles both static strings and Pulumi Output values. Methods include add() for static values, add_output() for Pulumi Outputs, and add_if() for conditional variables. Resolves all Outputs at build time using Output.all().apply().

Additional Utilities¶

9. Deployment¶

Prerequisites¶

1. AWS profile is configured via Pulumi config (pulumi config set aws:profile tradai), not as an environment variable. Configure infra/.env with the required variables (see infra/.env.example):
2. PULUMI_CONFIG_PASSPHRASE=<your passphrase>

3. S3_PULUMI_BACKEND_URL=s3://<pulumi-state-bucket>

4. The justfile _infra-run helper sources infra/.env automatically before running Pulumi commands, then logs into the S3 backend and selects the target stack.

Full Bootstrap (First Deployment)¶

just infra-bootstrap dev

This runs the full sequence: 1. just infra-up-persistent dev -- S3, DynamoDB, ECR, Cognito, CodeArtifact 2. just infra-up-foundation dev -- VPC, RDS, SQS, SNS 3. just lambda-bootstrap -- Build and push all 18 Lambda images to ECR 4. just service-push-all -- Build and push all service images to ECR 5. just infra-up-compute dev -- IAM, ALB, ECS, Lambda, Step Functions, EC2 6. just infra-up-edge dev -- API Gateway, WAF, CloudWatch

Individual Stack Commands¶

Default stack is dev for all commands.

Compute Pre-Flight Check¶

just infra-up-compute verifies that all 18 Lambda images exist in ECR before deploying. If any image is missing, it fails with instructions to run just lambda-bootstrap first. This prevents partial deployments where Lambda functions reference non-existent images.

10. Cross-Stack References¶

How It Works¶

Each stack exports named outputs via pulumi.export(). Downstream stacks read these using pulumi.StackReference(f"{org}/tradai-{stack_name}/{environment}").

Key Exports Per Stack¶

Reference Pattern¶

The org value defaults to "organization" and can be overridden via pulumi config set org <value>. Stack names match environments (dev, staging, prod), so a reference looks like: organization/tradai-persistent/dev.

Changelog¶

Dependencies¶