Deployment Plan: Amazon Client Integration

Author: Miguel Pinilla Date: 2026-05-07 Status: Planning

Summary

The four implementation streams (bff, item-module, operator, infrastructure) and the operator activity (split between two personas — accountOwner and devOps) converge here. This plan defines the merge order, the persona choreography, the per-partition rollout, the smoke test, and the rollback procedure for v1 of PDEV-446.

Personas

The operator activity has two human personas with distinct responsibilities and capabilities. The runbook (amazon-creators-api-onboarding.md) is the authoritative procedure for each; this plan summarises the choreography and inter-persona communication.

Persona	Capabilities	Responsibilities in this rollout
accountOwner	Primary owner of Arda’s Amazon Associates account (only persona Amazon allows to register for Creators API). Assume non-technical background.	Apply for Creators API access; create the Arda Cards Application; capture the credential triple; hand credentials to devOps securely and out-of-band.
devOps	1Password access to all Arda-{Env}OAM vaults and Arda-SystemsOAM; AWS console / CLI access to all partitions; authorisation to run amm.yml.	Receive credentials from accountOwner; populate the four partition vaults; verify accessibility; trigger amm.yml per partition; run smoke tests; notify accountOwner and engineering when rollout is complete.

Inter-persona communication. Two notifications are required during the rollout. Channel is left to the personas’ working agreement (Linear comment on PDEV-446, Slack DM, etc.) — the runbook does not prescribe one.

1. accountOwner → devOps: “credentials ready via ” — kicks off vault population.
2. devOps → accountOwner (and engineering): “rollout complete: dev/stage/demo/prod green, smoke tests pass” — closes the loop. Acceptable channels for the credential handover itself, in priority order: 1Password Send (preferred — link and one-time password delivered through two different channels), Slack DM (with mutual deletion after receipt), in-person or phone dictation. The runbook walks accountOwner through each step-by-step.

Pre-deploy gates

#	Gate	Owner	Evidence
1a	accountOwner has registered for Creators API, created the Arda Cards Application, and captured the credential triple.	accountOwner	Confirmation message to devOps + engineering (channel: personas’ choice) — “credentials ready via “.
1b	devOps has received credentials from accountOwner and populated all four Arda-{Env}OAM vaults with a multi-field Amazon Creators API entry.	devOps	for v in DevOAM StageOAM DemoOAM ProdOAM; do op item get "Amazon Creators API" --vault "Arda-${v}" --fields credentialId; done returns four non-empty values.
1c	OP_SERVICE_ACCOUNT_TOKEN GitHub Org secret exists and the underlying 1Password Service Account has read access to all four Arda-{Env}OAM partition vaults (required for amm.yml to call op read on each partition’s Amazon credentials).	devOps	Run the per-vault verification one-liner from the operator runbook § “Service account token (already provisioned)” for each of Arda-DevOAM, Arda-StageOAM, Arda-DemoOAM, and Arda-ProdOAM; all four return a non-empty Credential ID.
2	bff PR — CI green (lint, typecheck, build, Jest, Chromium e2e).	bff-stream engineer	PR Status checks pending → green.
3	item-module PR — CI green (./gradlew check).	item-module-stream engineer	Same.
4	infrastructure PR — CI green; gate #1b satisfied (verification command output recorded in PR body by devOps).	infrastructure-stream engineer (with devOps confirmation of 1b)	PR description includes the gate-#1b command output.
5	documentation PR — make pr-checks green; combines runbook + BFF API reference + planning artefacts.	(any contributor)	PR’s CI green.

Gates #2–#5 are independent and can be cleared in any order. Gates #1a → #1b are the hard ordering constraint for gate #4: gate #4 cannot clear until both #1a (accountOwner) and #1b (devOps) are satisfied, in that order, because infrastructure’s amm.sh reads the populated vaults at deploy time. See 2-implementation/infrastructure/task-plan.md § “Merge gate (the hard gate)”.

Merge order

The recommended merge order minimises the time the production deployment is in an inconsistent state (BFF code present but env vars missing, or vice versa). Owner column shows which persona/role drives each step.

Step	Action	Owner
1	Merge documentation PR — runbook + planning artefacts + BFF API reference. Merging this first makes the runbook URL stable for accountOwner to follow.	engineering
2	accountOwner activity — register for Creators API, create the Arda Cards Application, capture the credential triple, hand over to devOps securely. (External; no PR.)	accountOwner
3	accountOwner → devOps notification — “credentials ready via ”. Channel: personas’ choice.	accountOwner
4	devOps activity (vault population) — receive credentials, populate all four Arda-{Env}OAM vaults, run the verification one-liner, post the output to PDEV-446 / the infrastructure PR body. (External; no PR.)	devOps
5	Merge infrastructure PR — gate #1b verification recorded in PR body, CI green, then merge.	infrastructure-stream engineer
6	devOps activity (per-partition deploy) — run amm.yml for each of Alpha002/dev, Alpha002/stage, Alpha001/demo, Alpha001/prod in that order, materialising the Secrets Manager secrets and Amplify env vars. Smoke-test between partitions.	devOps
7	Merge bff PR — merge after step 6 completes for at least Alpha002/dev. The Amplify auto-build for arda-frontend-app on each partition picks up both the new code AND the new env vars on the same build, so the route is functional from the first deploy.	bff-stream engineer
8	Merge item-module PR — any time. Operations deploys via its own pipeline; no relationship to bff / infra timing.	item-module-stream engineer
9	devOps → accountOwner + engineering completion notification — “rollout complete: dev/stage/demo/prod green, smoke tests pass.” Update PDEV-446 with per-partition deploy timestamps.	devOps

Acceptable variations. If bff PR merges before step 3 finishes for all partitions: the route is deployed but non-functional on un-deployed partitions (route returns AMAZON_API_UNAVAILABLE because env vars are missing). No user-facing impact in v1 because no caller exists; acceptable.

If item-module PR merges before everything else: zero impact — the ItemPrinter change has no relationship to Amazon.

Per-partition rollout

Owned by devOps. The amm.yml GitHub Actions workflow takes a single environment per run (Alpha002/dev, Alpha002/stage, Alpha001/demo, Alpha001/prod). Recommended order:

1. Alpha002/dev — first. Lowest blast radius.
2. Alpha002/stage — second. Pre-prod validation.
3. Alpha001/demo — third. Full-IaC partition; exercises the amplify.cfn.yaml EnvironmentVariables path.
4. Alpha001/prod — last. The us-east-2 region anomaly applies; amm.sh reads the partition’s aws_region from the partition-config service and configures AWS credentials accordingly. Verify the deploy targets us-east-2 in the workflow logs.

Between steps run the smoke test (next section) before proceeding.

Smoke test

Owned by devOps. Small enough to inline. For each partition’s deployed BFF, after amm.sh completes successfully:

1. Authenticate. Use a real tenant user account for the partition (or a test user provisioned for QA). Obtain a JWT; record it as $JWT.

2. Hit the route. With ASIN B08N5WRWNW (a stable Kindle listing recommended by the original API exploration as a smoke-test reference):

   curl -sS -X POST "https://<partition-app-host>/api/amazon/import" \
     -H "Authorization: Bearer ${JWT}" \
     -H "Content-Type: application/json" \
     -d '{"input":"B08N5WRWNW"}'

3. Verify the response. Expect HTTP 200 with a JSON body matching the v1 DTO (per goal.md Success Criterion 2):

   • name — non-empty string, looks like a Kindle title.
   • image.url — https://m.media-amazon.com/images/I/... URL; image.width and image.height integers around 500.
   • price.amount — number; price.currency — "USD"; price.displayAmount — "$...".
   • unitCount, unit, upc — may be null for a Kindle; non-null for physical goods.
   • asin — "B08N5WRWNW".
   • productUrl — https://www.amazon.com/dp/B08N5WRWNW?tag=…&linkCode=ogi&... containing Arda’s affiliate tag and Amazon’s tracking parameters (verbatim from Amazon’s response per Constraint 3).

4. Check the error path. Hit the same route with an obviously bad input (e.g. {"input":"https://www.example.com/"}) and assert HTTP 4xx with the v1 error envelope { "ok": false, "code": "UNRECOGNIZED_AMAZON_URL", "message": "…" } (canonical shape per current-system/functional/reference-data/item/amazon-bff-api.md#response--errors).

5. (Optional) Check the throttle path. Send 10–15 requests in quick succession. v1 traffic should not approach the throttle ceiling on any partition; if AMAZON_API_THROTTLED does appear, record it as expected-but-noted.

If any step fails, halt the rollout and follow the rollback procedure for the partition.

Diagnostics — for the devOps persona overseeing the rollout

If a partition’s smoke test fails or the BFF logs show errors, the failure is most often in one of three layers. Check in this order:

1. Amazon Creators API SDK / upstream Amazon. Symptoms: AMAZON_API_UNAVAILABLE, AMAZON_API_THROTTLED, UnauthorizedException (TokenExpired / InvalidClient), or unexpected response-shape errors despite the credential triple being correct. Where to look:
   • BFF logs (CloudWatch). Filter for amazon, creators, Unauthorized, Throttle, AssociateNotEligible. Each error class is documented verbatim in ../context-exploration.md § “Error Model — Verbatim from Amazon”; cross-reference the message string to the upstream cause.
   • amazon-creators-api SDK behaviour. v1 pins exact version 1.2.2. If the SDK itself misbehaves (e.g. a regression in token caching or a serialisation bug), look for the SDK’s own error classes (UnauthorizedException, AccessDeniedException, etc.) in the BFF logs. The SDK does not emit telemetry; the BFF logs are the only signal.
   • Amazon Associates Central. The Link Type Performance report and the Creators API status page (Tools → Creators API in Associates Central) are the upstream signals. accountOwner owns access to these; loop them in if you suspect an upstream issue.
2. Env-var / IaC pipeline. Symptoms: route returns AMAZON_API_UNAVAILABLE immediately on every request because the four AMAZON_* env vars never reached the build. Where to look:
   • Amplify build logs for the partition. The build log shows which env vars the env | grep AMAZON_ allowlist line produced. Missing names → check amplify.yml is at the right SHA on the deployed branch (and that the inline BuildSpec is empty per Task 8b — the amm.sh Task 8c assertion catches this on the next deploy).
   • aws secretsmanager get-secret-value --secret-id <infrastructure>-<partition>-AmazonCreatorsApi — the underlying secret. Should return a JSON string with the four fields populated.
   • Amplify app env vars — aws amplify get-app --app-id <id> --query 'app.environmentVariables'. Should include the four AMAZON_* keys with values resolving via {{resolve:secretsmanager:...}}.
3. 1Password vault state. Symptoms: the partition’s amm.yml run aborts at op read time. Where to look:
   • The verification one-liner: for v in DevOAM StageOAM DemoOAM ProdOAM; do op item get "Amazon Creators API" --vault "Arda-${v}" --fields credentialId 2>&1 | head -1; done. If any vault returns an error, that’s the source.
   • The partition → vault map in amm.sh:170 — confirm prod=ProdOAM (the Task 5b fix). If it still reads prod=SystemsOAM, the prod deploy will look in the wrong vault.

For SDK-layer problems specifically (most disruptive case): there is no in-place rollback for the SDK version; if amazon-creators-api@1.2.2 itself proves broken at scale, revert the bff PR (which removes the route entirely — acceptable in v1 because no caller exists) and pin a different SDK version in a follow-up PR. The four env vars and the infrastructure work remain useful and do not need to be rolled back.

Rollback

Per partition, in reverse order of deploy:

1. Bff PR rollback. If the BFF route is broken on a partition, the arda-frontend-app Amplify build can be rolled back to the previous commit via git revert + push, OR by triggering a re-deploy of the previous Amplify build via the Amplify Console / API. The arda-frontend-app repo’s PR-revert workflow (if present) handles the standard case.
2. Infrastructure PR rollback. If the partition’s Amplify app or Secrets Manager secret is misconfigured: re-run amm.yml for that partition with the previous main commit (i.e. revert the infrastructure PR, then re-run). The amm.sh script is idempotent for re-runs against the same partition.
3. Item-module PR rollback. Standalone — revert the operations PR, redeploy. No relationship to bff / infra.
4. 1Password vault contents. Do not delete the credential triple from 1Password during rollback unless it has been compromised. Reverting the infrastructure PR removes the AWS Secrets Manager secret and the Amplify env var entries; the 1Password entry can stay populated for a future re-deploy.
5. accountOwner action. If the Creators API Application itself needs to be removed (e.g. legal hold, abuse), accountOwner deletes the credential set first, then the Application, in Associates Central. devOps then clears the four Arda-{Env}OAM vault entries. This is out of v1 scope and tracked separately if it ever becomes necessary.

Post-deploy verification

#	Check	When	Owner
1	Smoke test passes on each partition.	Immediately after each partition deploy.	devOps.
2	Amplify build logs do not show “Failed to load environment variables” for the four AMAZON_* names.	First Amplify build after env-var change.	devOps.
3	No UnauthorizedException (TokenExpired, InvalidClient) errors in the BFF logs.	First 24 hours post-rollout.	devOps / on-call.
4	AssociateNotEligible error not seen in BFF logs. If it appears, devOps notifies accountOwner to verify Arda’s qualified-sales standing.	First 30 days post-rollout.	devOps monitors logs; accountOwner owns recovery (eligibility maintenance).

Linear and CHANGELOG

• Linear ticket PDEV-446 is updated with merge dates of each PR.
• CHANGELOG entries land in each repo (arda-frontend-app, operations, infrastructure, documentation) with cross-references to PDEV-446.

References

• ../goal.md — project goal and success criteria.
• ../context-exploration.md — verbatim Amazon error model (drives the smoke-test assertions); IaC compliance per partition (drives the per-partition rollout).
• ../phases.md — stream structure.
• ../2-implementation/{bff, item-module, operator, infrastructure}/task-plan.md — the four implementation streams.

---

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