Specification: Frontend Deployment Pipeline

This document drives the implementation of the Arda frontend deployment pipeline. It is organized into four sequential runs, each with explicit entry/exit criteria and STOP points for review. See requirements.md for the full requirement set and verification.md for the traceability matrix.

Project Type

Modification — changes to existing infrastructure (amm.sh, CloudFormation templates, CDK constructs) and creation of new GitHub Actions workflows.

Project Directory

All plan documents are in documentation/src/content/docs/roadmap/backlog/requested/frontend-pipeline/plan/.

Run Overview

Run	Directory	Description	Repos	Requirements
1	`run-1-infrastructure/`	Demo environment + IAM role	`infrastructure`, `arda-frontend-app`	REQ-INFRA-001 through REQ-INFRA-007
2	`run-2-workflows/`	GitHub Actions workflows on `demo` branch	`arda-frontend-app`	REQ-WF-001 through REQ-WF-004
3	`run-3-validation/`	End-to-end pipeline validation	`arda-frontend-app` (triggers only)	REQ-WF-002 (redeploy), REQ-CUT-003 (rollback)
4	`run-4-cutover/`	Production migration + documentation	`infrastructure`, `arda-frontend-app`, `documentation`	REQ-CUT-001 through REQ-CUT-004, REQ-DOC-001 through REQ-DOC-003

Execution Sequence

Run 1: Infrastructure

What: Create the demo Amplify app, modify amm.sh with all mapping constants, add EnableAutoBuild parameter and AmplifyBranchName export to CloudFormation template, create the lightweight export template, add the frontend IAM role to the CDK construct. Deploy to both AWS accounts.

Acceptance: Demo Amplify app deployed and functional at demo.alpha001.app.arda.cards. IAM role exists in both accounts and is assumable via OIDC. Kyle deployment unaffected.

STOP: Review infrastructure changes before proceeding to workflow development. Verify the IAM role can be assumed from arda-frontend-app.

See run-1-infrastructure/project-plan.md for detailed tasks.

Run 2: Workflows

What: Create deploy.yaml, redeploy.yaml, and reusable_deployment.yaml on the demo branch. Configure GitHub environments. Test the deploy workflow against the demo partition.

Acceptance: deploy.yaml successfully triggers an Amplify build on the demo app. The site at demo.alpha001.app.arda.cards updates. GitHub environments are configured.

STOP: Review workflow files and confirm the first successful deployment before validation.

See run-2-workflows/project-plan.md for detailed tasks.

Run 3: Validation

What: Comprehensive testing of the pipeline — deploy, redeploy with specific SHA, CI check gate, site functionality verification.

Acceptance: All pipeline paths exercised and confirmed working. GO/NO-GO decision documented.

STOP: GO/NO-GO checkpoint. Do not proceed to cutover until all validation criteria pass and the decision to proceed is explicitly confirmed.

See run-3-validation/project-plan.md for detailed tasks.

Run 4: Production Cutover

What: Migrate existing Amplify apps incrementally (dev → stage → prod). Deploy lightweight export stacks. Enable PR previews. Update workflow trigger. Create documentation.

Acceptance: All four partitions deploy from main via the new pipeline. PR previews work on the dev app. Documentation complete.

See run-4-cutover/project-plan.md for detailed tasks.

Reference Data

Account and Partition Map

Partition	Account	Account ID	Infrastructure Prefix	Amplify Region	Amplify App ID	Amplify Branch Resource
dev	Alpha002	`139852620346`	`Alpha002`	`us-east-1`	`d38w5m1ngjza76`	`dev`
stage	Alpha002	`139852620346`	`Alpha002`	`us-east-1`	`d1kbrvra79y8sc`	`stage`
demo	Alpha001	`009765408297`	`Alpha001`	`us-east-1`	(created in Run 1)	`demo`
prod	Alpha001	`009765408297`	`Alpha001`	`us-east-2`	`duhexavnwh88g`	`main`

IAM Role Derivation

Partition	`aws_role` (from purpose-config)	Frontend Role (derived)
dev	`arn:aws:iam::139852620346:role/Alpha002-API-GitHubAction`	`arn:aws:iam::139852620346:role/Alpha002-API-GitHubActionFrontEnd`
stage	`arn:aws:iam::139852620346:role/Alpha002-API-GitHubAction`	`arn:aws:iam::139852620346:role/Alpha002-API-GitHubActionFrontEnd`
demo	`arn:aws:iam::009765408297:role/Alpha001-API-GitHubAction`	`arn:aws:iam::009765408297:role/Alpha001-API-GitHubActionFrontEnd`
prod	`arn:aws:iam::009765408297:role/Alpha001-API-GitHubAction`	`arn:aws:iam::009765408297:role/Alpha001-API-GitHubActionFrontEnd`

amm.sh Mapping Constants

# Partitions eligible for Amplify deployment steps
AMPLIFY_DEPLOY_TARGETS=("SandboxKyle002:kyle" "Alpha001:demo")

# Partition → Amplify branch resource name
declare -A AMPLIFY_BRANCH_NAMES=(
  [dev]="dev"
  [stage]="stage"
  [demo]="demo"
  [prod]="main"
  [kyle]="main"
)

# (Infrastructure:Partition) → GitHub repository
declare -A AMPLIFY_APP_REPOS=(
  [SandboxKyle002:kyle]="Arda-cards/kyle-frontend-app"
  [Alpha001:demo]="Arda-cards/arda-frontend-app"
  [Alpha002:dev]="Arda-cards/arda-frontend-app"
  [Alpha002:stage]="Arda-cards/arda-frontend-app"
  [Alpha001:prod]="Arda-cards/arda-frontend-app"
)

# (Infrastructure:Partition) → Amplify API region override
# Only needed when Amplify region differs from purpose-config aws_region
declare -A AMPLIFY_REGION_OVERRIDES=(
  [Alpha001:prod]="us-east-2"
)

Sensitive Information Locations

Secret	Location	Used By
`AMPLIFY_GITHUB_ACCESSTOKEN`	GitHub org secret OR 1Password: `Arda-SystemsOAM/Amplify_GitHub_AccessToken`	`amm.sh` → `amplify.cfn.yaml` `AccessToken` parameter
`ARDA_API_KEY_DEMO`	GitHub org secret (provisioned by `infrastructure/tools/sync-secrets-from-1password.sh`)	`amm.yml` → `partitionSecrets` CloudFormation step
`ARDA_API_KEY` (local)	1Password: `Arda-DemoOAM/ARDA-API-KEY/password`	Local `amm.sh` runs for demo partition
`ARDA_PURPOSE_LOCATOR_READER_TOKEN`	GitHub org secret	`purpose-configuration-action` in GHA workflows
`ARDA_PURPOSE_LOCATOR_BASE_URL`	GitHub org variable	`purpose-configuration-action` in GHA workflows

Existing Amplify App IDs (for cutover)

These values are from Amplify Current Configuration and must be verified against live AWS state before use:

Partition	App ID	Verification Command
dev	`d38w5m1ngjza76`	`aws amplify get-app --app-id d38w5m1ngjza76 --region us-east-1`
stage	`d1kbrvra79y8sc`	`aws amplify get-app --app-id d1kbrvra79y8sc --region us-east-1`
prod	`duhexavnwh88g`	`aws amplify get-app --app-id duhexavnwh88g --region us-east-2`

Quality Guidelines

All CloudFormation templates must pass aws cloudformation validate-template before deployment.
CDK changes must pass npx cdk synth for both Alpha001 and Alpha002 infrastructure apps.
GitHub Actions workflow YAML must pass lint validation.
Every deployment to an existing partition must be preceded by a Kyle regression check (Run 1) or verified against the previous partition (Run 4).
No secrets or environment variables shall flow through GitHub Actions. The workflow has only Amplify API permissions and cloudformation:ListExports.

Worktree Strategy

Work will take place in the main directories where the repositories are cloned. Each run works on a single branch per repository at a time, and the runs are sequential — no parallel branches require worktree isolation.

Pull Request Strategy

All changes reach main via PRs — no direct pushes to main in any repository.

#	Repo	Run	Branch	Content	Gate
PR1	`infrastructure`	Run 1	`jmpicnic/frontend-pipeline/infrastructure-changes` → `main`	All CFn templates, `amm.sh`, `amm.yml`, CDK role changes	Merge before Kyle check + demo deployment
PR2	`arda-frontend-app`	Run 4	`demo` → `main`	Three workflow files with full matrix + CI status check in `redeploy`	Merge before partition migration begins
PR3	`arda-frontend-app`	Run 4	`jmpicnic/frontend-pipeline/deploy-trigger-switch` → `main`	`deploy.yaml` trigger switch: add `workflow_run` on CI success	Merge after all partitions verified
PR4	`infrastructure`	Post-cutover	`jmpicnic/frontend-pipeline/oidc-cleanup` → `main`	Remove `refs/heads/demo` from IAM role OIDC trust	After pipeline is stable

Notes:

Each PR must include a CHANGELOG update in the target repository before merging. PR1 and PR4 update infrastructure/CHANGELOG.md. PR2 and PR3 update arda-frontend-app/CHANGELOG.md.
PR2 will be blocked by validate-pr-source.yml (expects PRs from stage, not demo). Options: admin bypass, temporary workflow relaxation, or update the check to allow demo as a source branch. Must be resolved before Run 4 Task 4.3.
No PRs in Runs 1–3 for arda-frontend-app: the demo branch is created directly (Run 1), workflows are pushed to it (Run 2), and validation runs against it (Run 3). No promotion to main until cutover.

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
P1	`COGNITO_REGION` anomaly: Prod app has `COGNITO_REGION=us-east-1` but Alpha001 Amplify is in `us-east-2`. The CFn template uses `!Ref "AWS::Region"` which would resolve to `us-east-1` for the demo app (deployed in `us-east-1`). This is consistent with prod — not a blocker.	(a) Accept as-is, (b) Investigate further	(a) Accept — demo will match prod behavior	Agreed.
P2	`AMPLIFY_REGION_OVERRIDES` in workflow: The reusable workflow needs to handle the prod region override. Should it (a) accept `amplify_region` as an input from the caller, or (b) maintain its own partition-to-region mapping?	(a) Input from caller, (b) Internal mapping	(a) Input from caller — keeps the reusable workflow generic	Agreed.
P3	Kyle app `AppName`: The Kyle Amplify app uses `kyle-frontend-app` as AppName. The `AMPLIFY_APP_REPOS` mapping includes the full `owner/repo` format. Should `AppName` (the short name) be a separate mapping or derived from the repo name?	(a) Separate mapping, (b) Derived (split on `/`, take second part)	(b) Derived — simpler, works for all current cases	Agreed.
P4	Export stack deployment for prod: The lightweight export stack for prod is deployed in `us-east-1` (per directive), but the Amplify App ID `duhexavnwh88g` refers to an app in `us-east-2`. The export is just a key-value pair — is there any concern with the export value referencing a resource in a different region?	(a) No concern — export is just a string, (b) Add a comment in the template	(a) No concern — the workflow uses the value with the correct Amplify region separately	Agreed.