Requirements: Frontend Deployment Pipeline

REQ-INFRA-001: Demo Amplify Application

The demo partition (Alpha001, 009765408297) shall have a fully provisioned Amplify application connected to a demo branch of arda-frontend-app, with auto-build disabled. The application shall resolve environment variables from the existing Alpha001-demo-* CloudFormation exports and Secrets Manager entries.

REQ-INFRA-002: EnableAutoBuild Parameter

The amplifyBranch.cfn.yaml CloudFormation template shall accept an EnableAutoBuild parameter of type String with allowed values "true" and "false", defaulting to "true". The AWS::Amplify::Branch resource shall use this parameter. Existing deployments (SandboxKyle002) shall be unaffected (they receive the default).

REQ-INFRA-003: AmplifyBranchName Export

The amplifyBranch.cfn.yaml template shall export the Amplify branch resource name as ${Infrastructure}-${Partition}-I-AmplifyBranchName. This export, combined with the existing ${Infrastructure}-${Partition}-I-AmplifyAppId export from amplify.cfn.yaml, provides all parameters the GitHub Actions workflow needs.

REQ-INFRA-004: Lightweight Export Stack

A CloudFormation template (amplifyExports.cfn.yaml) shall exist that publishes AmplifyAppId and AmplifyBranchName as CloudFormation exports for existing manually-created Amplify apps. Parameters: Infrastructure, Partition, AmplifyAppId, AmplifyBranchName. Exports follow the same naming convention as the main templates: ${Infrastructure}-${Partition}-I-AmplifyAppId and ${Infrastructure}-${Partition}-I-AmplifyBranchName. All export stacks shall be deployed in us-east-1 regardless of the Amplify app’s actual region.

REQ-INFRA-005: amm.sh Mapping Constants

The amm.sh script shall maintain the following explicit mapping constants:

1. AMPLIFY_DEPLOY_TARGETS: List of (Infrastructure, Partition) pairs eligible for Amplify deployment steps.
2. AMPLIFY_BRANCH_NAMES: Associative array mapping partition names to Amplify branch resource names (dev→dev, stage→stage, demo→demo, prod→main, kyle→main).
3. AMPLIFY_APP_REPOS: Mapping of (Infrastructure, Partition) to GitHub repository (Arda-cards/arda-frontend-app for Alpha001/Alpha002 partitions, Arda-cards/kyle-frontend-app for SandboxKyle002).
4. AMPLIFY_REGIONS: Mapping of (Infrastructure, Partition) to Amplify API region, defaulting to the purpose-config aws_region. Override: prod → us-east-2.

The Amplify deployment gate condition shall check AMPLIFY_DEPLOY_TARGETS instead of the current infrastructure-level exclusion.

REQ-INFRA-006: amm.yml Per-Environment Secret Selection

The amm.yml workflow shall use secrets[format('ARDA_API_KEY_{0}', partition)] for per-environment API key selection. The other four shared secrets (ARDA_SIGNUP_KEY, HUBSPOT_CLIENT_KEY, HUBSPOT_PAT, PYLON_WIDGET_KEY) remain as-is.

REQ-INFRA-007: Frontend IAM Role

A dedicated IAM role shall be created per AWS account via the GhOidcProvider CDK construct:

Property	Value
Name	${prefix}-API-GitHubActionFrontEnd
OIDC subject	repo:Arda-cards/arda-frontend-app
Branch scope	refs/heads/main, refs/heads/patch, refs/heads/demo
Permissions	amplify:StartJob, amplify:GetJob, amplify:GetApp, amplify:GetBranch, cloudformation:ListExports
Amplify resource scope	arn:aws:amplify:${region}:${account}:apps/*
CloudFormation resource scope	* (ListExports does not support resource-level restrictions)

The role shall be deployed to both Alpha001 (009765408297) and Alpha002 (139852620346).

REQ-WF-001: Deploy Workflow

A deploy.yaml workflow in arda-frontend-app shall:

1. During development: trigger via workflow_dispatch on the demo branch with matrix [demo]
2. After cutover: trigger via workflow_run on ci.yaml success on main (retaining workflow_dispatch as fallback) with matrix [dev, stage, demo, prod]
3. Deploy sequentially (max-parallel: 1)
4. Set environment: ${{ matrix.partition }} for authorization gates
5. Call reusable_deployment.yaml for each partition

REQ-WF-002: Redeploy Workflow

A redeploy.yaml workflow shall:

1. Accept partition (choice) and commit_sha (string) as workflow_dispatch inputs
2. Verify CI passed for the SHA via the commit status API; run CI inline if not available
3. Call reusable_deployment.yaml with the partition, commit SHA, and (for prod) amplify_region: us-east-2
4. Set environment: ${{ inputs.partition }} for authorization gates

REQ-WF-003: Reusable Deployment Workflow

A reusable_deployment.yaml shall:

1. Accept inputs: partition (string, required), commit_sha (string, optional), amplify_region (string, optional — defaults to purpose-config aws_region)
2. Set environment: ${{ inputs.partition }}
3. Require permissions: contents: read, id-token: write
4. Execute steps:
   • Fetch purpose-configuration → get aws_role, aws_region
   • Derive frontend role ARN: append FrontEnd to the role name in aws_role
   • Parse infrastructure prefix from role name (text before -API-GitHubAction)
   • Configure AWS credentials via OIDC using the derived frontend role ARN
   • Read CloudFormation exports from us-east-1: ${Infrastructure}-${Partition}-I-AmplifyAppId and ${Infrastructure}-${Partition}-I-AmplifyBranchName
   • If amplify_region differs from aws_region, reconfigure AWS CLI region for Amplify API calls
   • Call aws amplify start-job --app-id {id} --branch-name {name} --job-type RELEASE (with --commit-id if commit_sha provided)
   • Poll aws amplify get-job until status is SUCCEED or FAILED
   • Fail the workflow if deployment fails

REQ-WF-004: GitHub Environments

GitHub environments shall be configured on arda-frontend-app:

Environment	Protection Rules
dev	None
stage	required_reviewers: denisa, jmpicnic, danmerb, davequinta
demo	None
prod	required_reviewers: denisa, jmpicnic, danmerb, davequinta

REQ-CUT-001: Incremental Partition Migration

Each existing Amplify app (dev, stage, prod) shall be migrated individually and verified before proceeding to the next. Migration order: dev → stage → prod. Migration steps per partition:

1. Deploy lightweight export stack in us-east-1
2. Disable auto-build via aws amplify update-branch --no-enable-auto-build
3. Add partition to the deploy.yaml matrix
4. Trigger deployment and verify the site is functional

REQ-CUT-002: PR Preview Deployments

After cutover, Amplify PR previews shall be enabled on the dev app (d38w5m1ngjza76) branch resource. PR previews:

• Build the PR branch using the dev app’s environment variables
• Run npm run test (Jest) before npm run build as a quality gate
• Deploy to a temporary URL (e.g., pr-{N}.d38w5m1ngjza76.amplifyapp.com)
• Redeploy on each push to the PR branch
• Auto-delete on PR close/merge

No Cognito callback URL changes are needed (the app uses USER_PASSWORD_AUTH, not OAuth/OIDC).

REQ-CUT-003: Rollback Capability

Two rollback mechanisms shall be available:

1. Redeploy previous SHA: redeploy.yaml with a known-good commit SHA
2. Re-enable auto-build: Emergency fallback via aws amplify update-branch --enable-auto-build

REQ-CUT-004: Deploy Trigger Cutover

At cutover, deploy.yaml shall switch its primary trigger from workflow_dispatch to workflow_run on ci.yaml success on main, retaining workflow_dispatch as a secondary trigger.

REQ-DOC-001: Frontend Development Guide

A developer-facing guide shall be created at documentation/src/content/docs/process/craft/implementation/frontend-development.md covering:

• PR preview workflow (how to find preview URL, what backend it uses, quality gate)
• Production deployment pipeline (what happens after merge to main)
• Manual redeploy / rollback procedures
• Local development setup
• Environment map (URLs, partitions, accounts)

REQ-DOC-002: Rollback Plan

A rollback-plan.md document shall exist in the project working directory before cutover begins, documenting:

• Per-partition rollback commands (re-enable auto-build, trigger manual build)
• Redeploy procedure via redeploy.yaml
• Contact list and escalation path

REQ-DOC-003: Post-Cutover Instructions

A post-cutover-instructions.md document shall document deferred procedures:

• Production verification procedure at live.app.arda.cards
• validate-pr-source.yml relaxation sequence
• Branch deletion (dev, stage, demo) in arda-frontend-app
• Demo Amplify stack cleanup (if demo becomes permanent, skip)
• Removal of refs/heads/demo from IAM role OIDC trust conditions