shoc-frontend-new/infra/cdk/README.md

Infrastructure & CI/CD — SeaHaven SHOC frontend

AWS hosting for the Vite SPA, defined as an AWS CDK app local to this repo, deployed through the org's reusable GitHub Actions workflow.

• Hosting: private S3 bucket (origin) + CloudFront, served on the custom domain dev.seahaven.com (ACM *.seahaven.com, Route 53 apex alias).
• API: CloudFront proxies /api/* over HTTPS to api.dev.seahaven.com, so the SPA calls it same-origin (VITE_API_URL=/api) — no CORS, no mixed content.
• Env-specific values (domain, cert, zone, API host) live in cdk.json context so the CI cdk deploy picks them up with no flags.
• Auth: GitHub Actions → AWS via OIDC (no long-lived keys)
• CD workflow: .github/workflows/deploy.yml is a thin caller of the org's Sea-Haven-Industries/.github → cd-cdk.yaml. That workflow runs cdk deploy (provisions infra) then scripts/deploy-web.sh (builds + uploads the SPA).
• Infra is local to this repo (CDK in infra/cdk); the deploy role is created by this stack, not added to the central oidc-deploy-roles.yaml.
• Environments: dev only today, deployed on push to the dev branch.

infra/cdk/
  bin/app.ts            entry point (reads -c context)
  lib/frontend-stack.ts S3 + CloudFront + OAC + OIDC deploy role
scripts/deploy-web.sh   build SPA -> s3 sync -> CloudFront invalidation
.github/workflows/
  ci.yml                quality gates (lint / build / test / e2e)
  deploy.yml            caller of the org reusable cd-cdk.yaml (push to dev)

What the stack creates

Resource	Purpose
S3 bucket seahaven-shoc-frontend-dev	private origin (BLOCK_ALL, SSE, OAC-only reads)
CloudFront distribution	HTTPS, gzip/br; default behavior → S3, /api/* → backend (HTTP origin)
CloudFront Function (viewer request)	SPA routing: rewrites extensionless paths to /index.html (scoped to the S3 behavior, so it never touches /api)
IAM role githubdeploy-shoc-frontend-new-dev	assumed by GitHub Actions via OIDC, scoped to repo:Sea-Haven-Industries/shoc-frontend-new:ref:refs/heads/dev

The whole cd-cdk.yaml job runs as that role, so it holds: sts:AssumeRole on cdk-hnb659fds-* (for cdk deploy), cloudformation:DescribeStacks (cd-cdk's pre-flight/health-check + output reads), read/write on the bucket (s3 sync), and cloudfront:CreateInvalidation (cache bust). The OIDC provider is a singleton account resource — the stack only imports it (created in step 2), so cdk destroy can't delete a resource shared by other roles.

---

One-time setup (run by a human with admin AWS creds)

1. Authenticate to the AWS account

aws configure            # or: aws sso login --profile <admin>
aws sts get-caller-identity     # confirm the right account + region (us-east-1)

2. Ensure the GitHub OIDC provider exists (once per account)

aws iam list-open-id-connect-providers
# If none ends in token.actions.githubusercontent.com, create it (thumbprint is
# no longer required — AWS validates GitHub against its own trust store):
aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com

3. CDK bootstrap (once per account/region)

cd infra/cdk
npm ci
npx cdk bootstrap aws://<ACCOUNT_ID>/us-east-1

4. Domain, cert, and API origin (already wired for dev)

For dev these are set in cdk.json context (account 396287094661):

Context key	Value
domainNames	dev.seahaven.com
certificateArn	…:certificate/2b78e74f-… (ACM *.seahaven.com, us-east-1)
hostedZoneId / hostedZoneName	Z07671212N75U4YLPWZR8 / dev.seahaven.com
apiOriginDomain / apiOriginProtocol	api.dev.seahaven.com / https

The SPA calls /api same-origin; CloudFront proxies /api/* over HTTPS to api.dev.seahaven.com. The stack creates the apex A/AAAA alias in the hosted zone (which is in this account, delegated from the parent seahaven.com zone). For staging/prod, override these context keys per environment.

5. First deploy (locally, with admin creds)

The deploy role doesn't exist until the first cdk deploy, so bootstrap it locally. This provisions infra + the role:

cd infra/cdk
npx cdk deploy

Note the DeployRoleArn output. Then push the first content (or just push to dev and let CI do everything from here on):

# from repo root, optional manual first content publish:
STACK_NAME=shoc-frontend-dev AWS_REGION=us-east-1 bash scripts/deploy-web.sh

6. Set the one GitHub secret

cd-cdk.yaml takes the role ARN as a secret (not a variable):

REPO=Sea-Haven-Industries/shoc-frontend-new
gh secret set AWS_DEPLOY_ROLE_ARN --repo "$REPO" \
  --body "arn:aws:iam::<acct>:role/githubdeploy-shoc-frontend-new-dev"

(Or Settings → Secrets and variables → Actions → Secrets.)

7. From now on: push to dev

git push origin dev

ci.yml runs the quality gates and deploy.yml calls cd-cdk.yaml, which runs cdk deploy then scripts/deploy-web.sh. Watch the Actions tab, then open the SiteUrl output.

First-run verification: this first push is what actually exercises the role's permissions and the OIDC trust through the reusable workflow (the local bootstrap used admin creds and tested none of that). Watch for credential/OIDC errors and a green post-deploy step.

---

Adding staging / prod later

Separate accounts: deploy this stack there with -c envName=staging, -c deployBranch=<branch>, and -c apiOriginDomain=<that-env's-api-host>; set that repo's AWS_DEPLOY_ROLE_ARN secret; and add a job to deploy.yml. Because the SPA calls /api same-origin, the API host is per-environment CloudFront config (the apiOriginDomain context) — the build output is identical across environments, so nothing env-specific gets baked into vite build.

Notes

• Teardown: npx cdk destroy. The bucket uses RemovalPolicy.DESTROY + autoDeleteObjects (dev artifacts are reproducible) — change this for prod.
• CI and CD both fire on push to dev in parallel; a red-CI commit still deploys (matches the org's push-time-CD model). Gating deploy on CI is a follow-up, not part of enabling CICD.
• Local npm is pinned to v6; the committed package-lock.json is lockfileVersion 1. CI (Node 24 / npm 11) reads it fine via npm ci.