Skip to content

ADR-003: Use SST v4 for AWS Infrastructure-as-Code

Status

Accepted (2026-03-04)

Context

Reggie originally ran on three PaaS providers (Vercel, Railway, Supabase) with no infrastructure-as-code. This created:

  1. No reproducibility: Infrastructure was manually provisioned via dashboards
  2. Vendor lock-in: Each service had different deployment mechanisms
  3. Cost unpredictability: Three separate billing systems with no unified cost view
  4. No staging environment: No easy way to spin up isolated environments for testing

The migration happened before any production customers existed -- the lowest-risk time to move.

Requirements: - Deploy Next.js frontends, FastAPI backend, and RDS Postgres from a single config - Stay within or near AWS free tier - Support multiple stages (dev, staging, production) from the same codebase - TypeScript-based config (team already uses TypeScript)

Decision

Use SST v4 as the IaC framework to deploy to AWS.

Infrastructure defined in sst.config.ts: - VPC with public subnets (no NAT for cost savings) - RDS PostgreSQL db.t4g.micro (free tier eligible) - ECS Fargate 0.25 vCPU for FastAPI backend - CloudFront + Lambda for Next.js frontends (via SST Nextjs component) - 12 secrets via SST Secrets (backed by AWS SSM Parameter Store) - GitHub Actions OIDC for keyless deployment

Why SST over alternatives: - vs Terraform: SST is TypeScript-native, matches our stack. First-class Next.js and ECS support without boilerplate. - vs CDK: SST builds on CDK but adds higher-level components (Nextjs, Postgres, Service) that reduce config by ~80%. - vs Pulumi: SST's dev mode enables local development that mirrors production (same config, different runtime).

Consequences

Easier: - Single sst.config.ts defines entire infrastructure (~120 lines) - sst dev for local development, sst deploy --stage X for any environment - Secrets managed declaratively (sst secret set KEY value --stage staging) - GitHub Actions deploys via OIDC (no long-lived AWS credentials) - Cost: ~$10/month during free tier, ~$55/month after

Harder: - SST v4 is relatively new -- fewer community examples than Terraform - VPC component versioning caused breaking changes during setup (required sst remove + sst deploy) - Team needs AWS familiarity for debugging (CloudWatch, ECS, RDS)

Related: plans/aws-migration-sst.md (full migration plan), docs/infrastructure/sst.md (resource reference)