Phenom Production Environment

Top-level facts

Architecture in one diagram

                     Cloudflare (proxied)
                              │
                              ▼
                api.thephenom.app  →  ALB  →  ECS Fargate  →  Hasura graphql
                                                                    │
                                                                    │ admin secret
                                                                    ▼
                                                            RDS Postgres 17.4
                                                            (db.m5.large)

                Mobile / dev-nest clients
                              │
                              │  IdToken from Cognito  (us-east-1_knEL7cqS3)
                              ▼
            createPhenom / getPhenoms (Hasura Action)
                              │  forward_client_headers: true
                              ▼
            Lambda Function URL (auth: NONE, JWT verified inside)
                              │
                              ├──→  AWS Secrets Manager: phenom-prod-app-secrets
                              ├──→  Hasura admin (over ALB)
                              └──→  S3 presigned PUT/GET → phenom-prod-media-storage

Endpoints

Cognito

What the triggers do

• hasura-cognito-trigger (pre-token-generation) — adds https://hasura.io/jwt/claims to the JWT with x-hasura-user-id, x-hasura-default-role: user, and x-hasura-allowed-roles plus x-hasura-chat-role from the optional chat_members lookup.
• hasura-cognito-sync-users (post-confirmation, post-authentication) — upserts the new Cognito user into the users table using the Hasura admin secret. Schema is discovered via introspection so Cognito-attribute → column mapping is automatic.

Test account

Used by Postman + curl smoke tests. Treat as a shared smoke-test account; don’t store real user data on it.

Hasura

Pulling the admin secret

aws secretsmanager get-secret-value \
  --secret-id phenom-prod-app-secrets \
  --query SecretString --output text \
  | jq -r .graphql_admin_secret

Applying Hasura metadata

The phenom-backend repo has a GitHub Actions workflow (.github/workflows/deploy-hasura-production.yaml) that runs hasura migrate apply and hasura metadata apply against this endpoint when:

1. Anything under hasura/** is pushed to main (typical: a develop → main release merge), or
2. The workflow is dispatched manually from the Actions tab.

The workflow runs in the Production GitHub Environment so it requires:

• vars.HASURA_ENDPOINT = https://api.thephenom.app
• secrets.HASURA_ADMIN_SECRET = the value pulled above

Adding a required reviewer rule on the Production environment is recommended for prod safety.

To apply manually from your laptop:

cd ~/c/phenom-backend/hasura
ADMIN=$(aws secretsmanager get-secret-value --secret-id phenom-prod-app-secrets \
        --query SecretString --output text | jq -r .graphql_admin_secret)
hasura migrate apply --endpoint https://api.thephenom.app --admin-secret "$ADMIN" --database-name default
hasura metadata apply --endpoint https://api.thephenom.app --admin-secret "$ADMIN"

RDS

ALB

ECS

The HASURA_ACTION_PHENOM_URL env var on the graphql container resolves to the action-handler Function URL, which is how createPhenom and getPhenoms are wired.

Lambdas

The action-handler reads phenom-prod-app-secrets for the Hasura admin secret and writes presigned S3 URLs against phenom-prod-media-storage.

S3 buckets

S3 keys for new uploads use the shape media/<phenomId>/<sortOrder>_<phenomId>_<sanitizedFilename> so multiple files for the same phenom don’t collide.

Secrets Manager

DNS

api.thephenom.app is the only ALB-fronted hostname in production.

Deferred services (dev-only today)

These exist in development and may land in prod later via a fresh Terraform PR. They are deliberately not deployed yet.

Applying infrastructure changes

cd ~/c/phenom-infra

# 1. Make changes on a feature branch
git checkout -b feat/your-change
# … edit environments/production/*.tf …

# 2. Plan + commit + open PR
cd environments/production
terraform plan
git add -A && git commit -m "feat(infra): your change"
gh pr create --base main

# 3. Once merged, sync main and apply
git checkout main && git pull
cd environments/production && terraform apply

For high-risk changes (anything that destroys, replaces, or rotates a secret), prefer terraform apply -target=... to scope the blast radius.

Smoke-testing the signing flow

The repo phenom-backend/hasura/postman/ ships a Postman collection plus three environment files (local / staging / production). Import in Postman, pick the Phenom — AWS production environment, then run:

1. Sign in to Cognito → captures id_token
2. createPhenom (multi-file) → captures phenom_id, upload_url for the first file
3. PUT to upload_url (pick any small file in the request body)
4. getPhenoms → returns row + signed_uri
5. GET signed_uri → bytes round-trip

Or via curl + the test account from above:

JWT=$(aws cognito-idp initiate-auth \
  --client-id 8uun49ru7f3fdvmlc12vqig3a \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=test@thephenom.app,PASSWORD='PhenomProd!2026' \
  --query 'AuthenticationResult.IdToken' --output text)

curl -s -X POST https://api.thephenom.app/v1/graphql \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"query":"mutation($i: CreatePhenomInput!) { createPhenom(input: $i) { phenomId uploads { filename uploadUrl } } }",
       "variables":{"i":{"lat":40.7,"lng":-74.0,"filenames":["smoke.txt"],"media_type":"image"}}}' \
  | jq

Cost snapshot

Major levers if cost matters:

• Single NAT Gateway instead of two (saves ~$32, loses multi-AZ redundancy)
• db.t3.medium instead of db.m5.large (saves ~$75, burstable CPU vs guaranteed)