Goal: Arda Frontend Deployment Pipeline

Objective

Transition the Arda frontend deployment pipeline from the current Amplify branch-sync model (dev → stage → main promotion) to a GitHub Actions–orchestrated pipeline that deploys from the main branch to all partitions sequentially, matching the backend (operations) deployment pattern.

Current State

The frontend (arda-frontend-app) deploys via three separate Amplify apps, each connected to a dedicated git branch:

Partition	Branch	Amplify App ID	Account	Region	URL
dev	`dev`	`d38w5m1ngjza76`	Alpha002 (`139852620346`)	`us-east-1`	`dev.alpha002.app.arda.cards`
stage	`stage`	`d1kbrvra79y8sc`	Alpha002 (`139852620346`)	`us-east-1`	`stage.alpha002.app.arda.cards`
prod	`main`	`duhexavnwh88g`	Alpha001 (`009765408297`)	`us-east-2`	`live.app.arda.cards`

Promotion requires a separate PR per stage (dev → stage → main), each with review, CI, and approval — tripling release cycle time. The validate-pr-source.yml workflow enforces this chain.

Target State

All Amplify apps point at main with auto-build disabled. GitHub Actions owns the deployment orchestration:

A developer opens a PR against main. Amplify PR previews provide fast feedback on the dev app. GitHub Actions CI (lint, build, test, e2e) gates the merge.
On merge to main, deploy.yaml fires (via workflow_run on CI success) and deploys sequentially: dev → stage → demo → prod with authorization gates on stage and prod.
redeploy.yaml allows targeted single-partition deployment of a specific commit SHA (with CI verification).

Amplify remains the build and hosting platform — it resolves environment variables, runs the build, and serves the SSR application. GitHub Actions only calls StartJob + polls GetJob. No secrets or environment variables flow through GitHub Actions.

Constraints

Additive: The new pipeline coexists with the current pipeline until fully validated. No existing Amplify apps are modified until production cutover.
Manual trigger first: The new pipeline starts as workflow_dispatch; switches to workflow_run at cutover.
Main branch only: After cutover, all deployments originate from main after CI passes.
No changes to purpose-configuration: All additional mappings (Repo, AppName, branch names, Amplify App IDs, Amplify regions) are maintained as explicit constants in amm.sh.
StartJob only: StartDeployment (zip upload) does not work for SSR/WEB_COMPUTE apps. StartJob with jobType: RELEASE is the only viable API.

Key Design Decisions

Decision	Rationale
Dedicated IAM role (`${prefix}-API-GitHubActionFrontEnd`)	Minimal permissions; scoped to `arda-frontend-app` repo only
`StartJob` (not `StartDeployment`)	`StartDeployment` doesn’t support SSR/`WEB_COMPUTE` apps
Demo Amplify app for development	Zero risk to existing pipeline until cutover
Sequential matrix (`max-parallel: 1`)	Matches backend pattern; catches issues before prod
Reusable workflows only (no composite actions)	`StartJob` + poll is simple enough
All mappings in `amm.sh` (not purpose-configuration)	Single source of truth for infrastructure constants
CloudFormation export stacks in `us-east-1` for all partitions	Uniform region for export reads; Amplify API region handled separately
Amplify PR previews on dev app	Built-in feature; no workflow changes; automatic cleanup

Region Topology

Partition	CloudFormation Exports Region	Amplify API Region	Notes
dev	`us-east-1`	`us-east-1`	—
stage	`us-east-1`	`us-east-1`	—
demo	`us-east-1`	`us-east-1`	New app, created by `amm.sh`
prod	`us-east-1`	`us-east-2`	Historical anomaly; existing app in `us-east-2`

The reusable GitHub Actions workflow accepts an amplify_region parameter (defaults to the purpose-config aws_region). The deploy.yaml matrix overrides this to us-east-2 for the prod partition.

Repositories Affected

Repository	Changes
`infrastructure`	CloudFormation templates, `amm.sh` mappings, CDK IAM role, `amm.yml` workflow
`arda-frontend-app`	GitHub Actions workflows (on `demo` branch, then merged to `main`), GitHub environments
`documentation`	”How to Develop in the Front End” guide
`purpose-configuration`	No changes

Development Strategy

The pipeline is developed and validated on an isolated demo partition (Alpha001) before touching any existing Amplify app. The demo Amplify app is created from the same CloudFormation templates, connected to a demo branch with auto-build disabled. Once validated, existing apps are migrated incrementally (dev → stage → prod), each verified before proceeding.