Skip to content

Solutions Directory

This directory contains documented solutions for complex problems encountered during Reggie development and deployment.

AWS Migration via SST

File: aws-migration-sst-complete-solution.md

Status: Phase 2 deployed to dev stage (2026-03-05)

Complete documentation of the migration from PaaS (Vercel + Railway + Supabase) to AWS using SST infrastructure-as-code framework.

Four Critical Fixes

  1. Docker Build Context Optimization (Fix 1)
  2. Problem: 1.5 GB monorepo sent per build
  3. Solution: Set image.context: "./backend" in SST config

  4. Impact: 140x faster builds

  5. Environment Variable Mapping (Fix 2)

  6. Problem: SST link feature doesn't construct DATABASE_URL that FastAPI expects
  7. Solution: Use $interpolate to construct URL from RDS properties

  8. Impact: FastAPI can read all required environment variables from SST secrets

  9. Database Schema Bootstrap (Fix 3)

  10. Problem: Alembic migrations reference Supabase-specific schemas (auth.*) that don't exist on fresh RDS
  11. Solution: Use Base.metadata.create_all() + alembic stamp head to bootstrap schema on fresh instances

  12. Impact: RDS provisioning completes without migration errors

  13. SST v4 VPC Component Versioning (Fix 4)

  14. Problem: Breaking changes in sst.aws.Vpc component between SST versions
  15. Solution: sst remove --stage <stage> then sst deploy --stage <stage>
  16. Impact: VPC created with latest component format

Key Files

  • SST Configuration: sst.config.ts (incorporates all four fixes)
  • Docker Configuration: backend/Dockerfile (multi-stage build)
  • Bootstrap Script: backend/scripts/bootstrap_schema.py (schema initialization)
  • App Configuration: backend/app/config.py (environment variable parsing)

Deployment Status (dev stage)

Service URL Status
Web App https://d1kvp1h7e9gtgw.cloudfront.net Live (200)
Admin App https://d3dl7l95t7kngj.cloudfront.net Live (307 → login)
Backend API http://ReggieApiLoadBa-doktwzst-534252255.eu-west-2.elb.amazonaws.com Live (health: connected)
API Docs http://ReggieApiLoadBa-doktwzst-534252255.eu-west-2.elb.amazonaws.com/api/v1/docs Live (200)

Architecture

  • Frontend: CloudFront + Lambda + S3 (Next.js via SST)
  • Backend: ECS Fargate 0.25 vCPU (FastAPI) + ALB
  • Database: RDS PostgreSQL db.t4g.micro (free tier)
  • Networking: No NAT, public subnets for cost savings
  • Auth: Clerk (migrated from Supabase Auth -- see ADR-001)
  • Storage: Cloudflare R2 (EU jurisdiction)

Quick Start

Deploy to dev: 

sst deploy --stage dev

Bootstrap RDS schema (one-time): 

doppler run --project reggie-backend --config dev -- python -m scripts.bootstrap_schema

Run smoke tests: 

make smoke-test URL=http://ReggieApiLoadBa-doktwzst-534252255.eu-west-2.elb.amazonaws.com

Local development (unchanged): 

make dev

Known Gaps

  • ML models not in Docker image — Rules engine works, ML ensemble unavailable
  • SKIP_MIGRATIONS=true hardcoded — Can remove once bootstrap is confirmed operational
  • Auth JWT validation — Needs SUPABASE_SERVICE_ROLE_KEY configuration

Cost Estimate

Item Monthly
Free tier (12 months) ~$10
After free tier expires ~$55
  • Full plan: plans/aws-migration-sst.md (4 phases)
  • Migration workflow: docs/solutions/workflow-issues/ci-migration-fails-fresh-db-20260224.md
  • Enterprise architecture review: docs/enterprise-architecture-review.md
  • Developer guide: CLAUDE.md

Troubleshooting

See "Troubleshooting Quick Reference" in aws-migration-sst-complete-solution.md for common errors and fixes.