Choreography: AWS Infrastructure for Item Image Upload

Execution Sequence

Order	Run	Directory	Trigger	Estimated Tasks
1	Run 1: DNS Foundation	run-1-dns-foundation/	Manual	7
2	Run 2: Partition Resources	run-2-partition-resources/	After Run 1 exit gate passes + DNS deployed	23

Artifact Dependency Map

Artifact	Produced By	Consumed By	Path	Format
assetsHostedZone import	Run 1	Run 2	src/main/cdk/apps/Al1x/util.ts	TypeScript
assetsCertificateArn import	Run 1	Run 2	src/main/cdk/apps/Al1x/util.ts	TypeScript
assetsDomain() function	Run 1	Run 2	src/main/cdk/platform/ari-configuration.ts	TypeScript
Deployed assets.arda.cards zone	Run 1	Run 2	AWS Route53 (root account)	Runtime
Deployed ACM cert	Run 1	Run 2	AWS ACM (infra account)	Runtime
6 cross-stack exports	Run 2	Phase 2 (operations)	CloudFormation exports	Runtime
Signing private key	Run 2	Phase 3b (BFF)	AWS Secrets Manager	Runtime

Hand-Off Protocol

All hand-offs are filesystem-only for code artifacts. Runtime artifacts (deployed zones, certificates) are verified via CLI commands.

Between Run 1 and Run 2

1. Run 1 completes all code changes and validate-exit.sh passes for code criteria.
2. Deployment gate: Run deploy-root.sh to deploy the root zone, then amm.sh for the infrastructure step to deploy the subdomain zone and certificate.
3. Wait for ACM certificate issuance — DNS validation may take minutes. Check with:

   aws acm list-certificates \
     --query "CertificateSummaryList[?DomainName=='*.alpha002.assets.arda.cards'].Status"

   Expected: ISSUED.
4. Run 2’s entry criteria are checked (code artifacts in repo + deployed infrastructure in AWS).
5. Run 2 is launched.

After Run 2

1. Run 2 completes all code + test tasks and validate-exit.sh passes.
2. Deploy Alpha002/dev: amm.sh Alpha002 dev — first deployment. Run verify-image-cdn.ts against dev.
3. Deploy Alpha002/stage: amm.sh Alpha002 stage — verifies multi-partition coexistence.
4. Deploy Alpha001/demo: Requires Phase 0 deployed to Alpha001 first (deploy-root.sh + amm.sh Alpha001 demo infra step). Then amm.sh Alpha001 demo full partition.
5. Deploy Alpha001/prod: amm.sh Alpha001 prod — production.
6. Deploy SandboxKyle002/kyle: Requires Phase 0 deployed to SandboxKyle002. Then amm.sh SandboxKyle002 kyle.
7. PR: Open a single PR from the integration branch to main.

Worktree Strategy

Single repository (infrastructure) — worktrees grouped under image-upload-infrastructure-worktrees/infrastructure/.

Run	Branch	Base
1	jmpicnic/image-upload-infrastructure/run-1	main
2	jmpicnic/image-upload-infrastructure/run-2	Run 1 branch

Integration: Run 2 branches from Run 1’s branch (not main), so it has access to Run 1’s code changes. The final PR merges Run 2’s branch (which includes Run 1’s commits) to main.

Cleanup: After the PR is merged, remove the worktree:

git -C /Users/jmp/code/arda/infrastructure worktree remove \
  /Users/jmp/code/arda/image-upload-infrastructure-worktrees/infrastructure

Recovery Procedures

Run 1 fails mid-execution

• Diagnosis: Check which tasks completed by reviewing git diff. Run 1 modifies 5 files — each is independent and can be fixed individually.
• Retry: Fix the failing task, re-run npm run ci-check.
• Root account failure: If deploy-root.sh fails, check AWS CloudFormation console for the RootConfiguration stack. The stack supports rollback.

Run 1 exit gate fails

• DNS not resolving: NS delegation may take up to 48 hours (rare). Check that NS records exist in the root zone: aws route53 list-resource-record-sets --hosted-zone-id <root-zone-id>.
• ACM cert not issuing: Check that the CNAME validation record exists in the subdomain zone. ACM creates these automatically during cdk deploy; if missing, re-deploy the infra ingress stack.

Run 2 fails mid-execution

• Diagnosis: Run npm test to identify failing tests. Run npm run ci-check to identify synth failures.
• Construct errors: Each construct is independent — fix the failing construct and re-run tests.
• Stack wiring errors: Check partition.ts for correct dependency ordering and prop passing.

Run 2 exit gate fails

• Deploy failures: Check CloudFormation console for stack events. Common issues: IAM permissions, cross-stack export not found (verify Run 1 deployment succeeded).
• Verification script fails: Run individual steps manually to isolate the failure (presigning, upload, CloudFront access, cookies).

Launch Commands

Run	Command
1	/launch-team 1-aws-infrastructure/plan/run-1-dns-foundation
2	/launch-team 1-aws-infrastructure/plan/run-2-partition-resources

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved