Deployment

Infrastructure is OpenTofu, organized into ordered stacks. All infra changes go through the CI pipeline (build.sh).

Never run tofu plan or tofu apply locally. Safe read-only operations (tofu fmt -check, tofu validate) are fine.

Apply order


account_prep -> data -> backend -> proxy
                                 -> frontend

Cross-stack references are resolved via AWS data sources using deterministic resource names — there is no terraform_remote_state.

Validate (no AWS interaction)


cd infrastructure/resources/aws/agent_runner/backend && tofu fmt -check
cd infrastructure/resources/aws/agent_runner/backend && tofu validate -var-file=../dev.tfvars
# repeat per stack directory

Lambda packaging

The CI build packages each function zip with the handler file, backend/lambda/common/, and the shared/ library installed as a regular package (not editable).

Secrets

Secrets live in AWS Secrets Manager under agent-runner/<env>/... and are referenced by ARN in Lambda environment variables. These must be pre-populated before the first apply:

STRIPE_SECRET_KEY
COGNITO_GOOGLE_CLIENT_SECRET
Cognito GitHub / Microsoft secrets (optional)

See docs/google-oauth-setup.md and docs/stripe-setup.md in the repo.

See Infrastructure Stacks for what each stack provisions and Environments for per-stage configuration.