Choreography: Frontend Deployment Pipeline

Execution Sequence

Order	Run	Directory	Trigger	Repos
1	Run 1: Infrastructure	run-1-infrastructure/	Manual	infrastructure, arda-frontend-app
2	Run 2: Workflows	run-2-workflows/	After Run 1 exit gate passes	arda-frontend-app
3	Run 3: Validation	run-3-validation/	After Run 2 exit gate passes	arda-frontend-app
4	Run 4: Cutover	run-4-cutover/	After Run 3 GO/NO-GO decision	infrastructure, arda-frontend-app, documentation

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path/Location	Format
demo branch	Run 1	Run 2	arda-frontend-app repo, branch demo	Git branch
amplifyBranch.cfn.yaml (modified)	Run 1	Run 1 (deploy), Run 4 (reference)	infrastructure/src/main/cfn/amplifyBranch.cfn.yaml	CloudFormation YAML
amplifyExports.cfn.yaml	Run 1	Run 4 (deploy for dev/stage/prod)	infrastructure/src/main/cfn/amplifyExports.cfn.yaml	CloudFormation YAML
amm.sh (modified)	Run 1	Run 1 (deploy), Run 4 (deploy export stacks)	infrastructure/amm.sh	Bash
amm.yml (modified)	Run 1	Run 1 (deploy via GH Actions)	infrastructure/.github/workflows/amm.yml	GHA YAML
gh-oidc-provider.ts (modified)	Run 1	Run 1 (CDK deploy)	infrastructure/src/main/cdk/constructs/oam/gh-oidc-provider.ts	TypeScript
Alpha001-demo CloudFormation stacks	Run 1	Run 2 (workflow reads exports)	AWS CloudFormation (us-east-1)	Stacks
IAM roles (both accounts)	Run 1	Run 2 (OIDC assumption)	AWS IAM	Roles
CloudFormation exports (demo)	Run 1	Run 2, Run 3 (workflow reads)	Alpha001-demo-I-AmplifyAppId, Alpha001-demo-I-AmplifyBranchName	CFn exports
deploy.yaml	Run 2	Run 3, Run 4	arda-frontend-app/.github/workflows/deploy.yaml	GHA YAML
redeploy.yaml	Run 2	Run 3, Run 4	arda-frontend-app/.github/workflows/redeploy.yaml	GHA YAML
reusable_deployment.yaml	Run 2	Run 3, Run 4	arda-frontend-app/.github/workflows/reusable_deployment.yaml	GHA YAML
GitHub environments	Run 2	Run 3, Run 4	arda-frontend-app GitHub settings	Config
PR1 (merged)	Run 1	Run 1 (deploy), Run 2 (entry criterion)	infrastructure repo, merged to main	Git PR
GO/NO-GO decision	Run 3	Run 4 (gate)	run-3-validation/go-no-go.md	Markdown
PR2 (merged)	Run 4	Run 4 (partition migration)	arda-frontend-app repo, demo → main	Git PR
PR3 (merged)	Run 4	Ongoing operations	arda-frontend-app repo, trigger switch	Git PR
Lightweight export stacks (dev/stage/prod)	Run 4	Run 4 (workflow reads)	AWS CloudFormation (us-east-1)	Stacks
rollback-plan.md	Run 4	Run 4 (reference during cutover)	Plan directory	Markdown
post-cutover-instructions.md	Run 4	Post-project (deferred)	Plan directory	Markdown
Frontend development guide	Run 4	Developers (ongoing)	documentation/src/content/docs/process/craft/implementation/frontend-development.md	Markdown

Pull Request Strategy

All changes reach main via PRs — no direct pushes to main in any repository. See specification.md — Pull Request Strategy for the full table.

PR	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

Hand-Off Protocol

All hand-offs are filesystem-only and AWS-state-only — no in-memory state is shared between runs. Each run reads its inputs from Git repositories, AWS CloudFormation exports, and files produced by prior runs.

Between Run 1 and Run 2

1. Run 1 completes and its validate-exit.sh passes.
2. Operator verifies:
   • PR1 merged: infrastructure changes are on main
   • demo branch exists in arda-frontend-app
   • CloudFormation exports are available: Alpha001-demo-I-AmplifyAppId, Alpha001-demo-I-AmplifyBranchName
   • IAM role Alpha001-API-GitHubActionFrontEnd is assumable from arda-frontend-app
3. Run 2 starts on the demo branch of arda-frontend-app.

Between Run 2 and Run 3

1. Run 2 completes and its validate-exit.sh passes.
2. Operator verifies:
   • All three workflow files exist on the demo branch
   • deploy.yaml has been triggered at least once and succeeded
   • GitHub environments are configured
3. Run 3 starts (no code changes — only workflow triggers and manual verification).
4. No PRs in Runs 2–3: workflow development and validation happen entirely on the demo branch.

Between Run 3 and Run 4

1. Run 3 completes and its validate-exit.sh passes.
2. GO/NO-GO decision: Operator reviews run-3-validation/go-no-go.md and explicitly confirms the decision to proceed with production cutover.
3. All stakeholders (denisa, jmpicnic, danmerb, davequinta) are notified of the cutover plan.
4. Run 4 begins with the rollback plan document.
5. PR2 (demo → main) is created early in Run 4, before partition migration begins.
6. PR3 (trigger switch) is created after all partitions are verified.

Recovery Procedures

Run 1 fails mid-execution

• CloudFormation stack failure: Check aws cloudformation describe-stack-events for the failed stack. Fix the template and redeploy. CloudFormation rollback is automatic for failed creates.
• CDK synth failure: Fix the TypeScript code and re-run npx cdk synth.
• Kyle regression: If the Kyle deployment breaks, revert the infrastructure changes and redeploy Kyle via amm.sh SandboxKyle002 kyle.

Run 2 fails mid-execution

• Workflow YAML errors: Fix on the demo branch and re-push. No impact on existing pipeline.
• OIDC assumption failure: Verify the IAM role trust policy matches the repository and branch. Check refs/heads/demo is in the OIDC subject conditions.
• StartJob failure: Check the Amplify Console for error details. Common issues: wrong app ID, wrong branch name, missing environment variables.

Run 3 exit gate fails

• Return to Run 2 to fix workflow issues, then re-run validation.
• If the issue is infrastructure (wrong exports, role permissions), return to Run 1.

Run 4 fails during partition migration

• Per-partition rollback: Re-enable auto-build on the affected partition:

  aws amplify update-branch --app-id {id} --branch-name {branch} --enable-auto-build --region {region}

• Do not proceed to the next partition until the current one is verified.
• If multiple partitions fail, consult the rollback plan and consider reverting to the pre-cutover state entirely.

Launch Commands

Run	Command	PRs
1	Work in infrastructure repo; create and merge PR1; deploy via amm.sh or amm.yml workflow	PR1
2	Work on demo branch of arda-frontend-app; push workflows; configure environments via GitHub UI/CLI	None
3	Trigger workflows via GitHub Actions UI; manual site verification	None
4	Create and merge PR2 (demo → main); deploy export stacks; migrate partitions; create and merge PR3 (trigger switch)	PR2, PR3