Phases: Amazon Client Integration

The project is structured as three phases. Phase 1 is the planning artefacts at the project root (this directory). Phase 2 is implementation, decomposed into four parallel streams that have no code-level dependencies on each other and can be developed concurrently. Phase 3 is deployment and verification.

Phase structure

#	Phase	Location	Status
1	Planning	This directory’s root: `goal.md`, `context-exploration.md`, `phases.md` (this file)	Complete (2026-05-07)
2	Implementation (four parallel streams)	`2-implementation/{bff, item-module, operator, infrastructure}/task-plan.md`	Complete (2026-05-08): all four streams shipped via arda-frontend-app#832, operations#169, infrastructure#451, and documentation#75
3	Deployment & verification	`3-deployment/deployment-plan.md`	Complete (2026-05-08): rolled out dev → stage → demo → prod; prod-rollout blocker tracked as PDEV-452 and fixed via infrastructure#452

Phase 2 — the four streams

The four streams share no code-level dependencies; they only converge at deployment. Each owns one PR (or a small set) in one repository, with its own task-plan.md. The streams can be developed by different agents / engineers concurrently.

Stream	Repository	Brief	Approx. size
`bff`	`arda-frontend-app`	New BFF Route Handler (`/api/amazon/import`), Creators API client wrapping the `amazon-creators-api` SDK, Shared utilities (ASIN extractor, affiliate-URL builder, types, `MARKETPLACE` constant), `src/lib/env.ts` additions, `amplify.yml` allowlist additions, unit tests.	Medium
`item-module`	`operations`	Branch `service/ItemPrinter.signImageUrl` on host: sign CDN-host URLs as today; pass through any non-CDN URL (Amazon-hosted images) unchanged. Two files (`ItemPrinter.kt` + tests).	Tiny
`operator`	`documentation`	Operator runbook for the Account Holder persona at `process/sre/runbooks/amazon-creators-api-onboarding.md`. Steps to register Creators API, create the Application, populate the four 1Password vault entries.	Small
`infrastructure`	`infrastructure`	Add the four `AMAZON_*` values to the existing 1Password → AWS Secrets Manager → Amplify env-var pipeline: edits to `partitionSecrets.cfn.yaml`, `amplify.cfn.yaml` (full-IaC partitions only), and `amm.sh` (including the partial-IaC `jq`-merge extension for `Alpha002:dev`, `Alpha002:stage`, `Alpha001:prod`).	Medium

Phase 2 entry checklist

Before Phase 2 execution begins, all of the following must be satisfied. This checklist is the gate for kicking off any of the four implementation streams.

#	Precondition	Evidence
1	Phase 1 planning artefacts (`goal.md`, `context-exploration.md`, `phases.md`) finalised on the integration branch and reviewed.	`documentation` PR for the planning artefacts is at minimum in Ready for review with no blocking comments.
2	All four `2-implementation/{bff, item-module, operator, infrastructure}/task-plan.md` finalised, cross-referenced consistently (task numbering, vault names, persona attributions, env-var spellings), and reviewed.	Same `documentation` PR as #1 covers these.
3	`3-deployment/deployment-plan.md` finalised on the same branch.	Same `documentation` PR.
4	1Password partition-vault names (`Arda-DevOAM`, `Arda-StageOAM`, `Arda-DemoOAM`, `Arda-ProdOAM`) confirmed by the `devOps` persona — including that `Arda-ProdOAM` is the canonical prod vault (not `Arda-SystemsOAM`, which is workspace-wide for system-level secrets only).	Direct confirmation from `devOps`; matches `infrastructure/task-plan.md` Task 5b.
5	`accountOwner` persona identified by name and reachable; `devOps` persona identified by name and reachable; both have agreed to a communication channel for the two notification events (handover-ready and rollout-complete).	Recorded in PDEV-446 or the operator runbook draft.
6	Worktrees on the four target repos (`arda-frontend-app`, `operations`, `infrastructure`, `documentation`) are rebased onto current `origin/main` and clean.	`git status` clean and `rev-list --left-right --count origin/main...HEAD` shows zero commits behind on each.
7	No conflicting in-flight work on the four target repos that would compound merge risk during Phase 3 rollout (e.g. concurrent `infrastructure` PRs touching `amm.sh`, `partitionSecrets.cfn.yaml`, or `amplify.cfn.yaml`).	Quick scan of open PRs on each repo at kickoff.

If any item is unmet, surface it before spawning agents — Phase 2 cannot start cleanly without it. (Items 4 and 5 are typically the long-pole because they involve human coordination outside the engineering loop.)

Documentation accumulation strategy

Per project decision (2026-05-07): the documentation repo accumulates updates from the streams in a single integration branch (jmpicnic/amazon-client-integration). Specifically:

Phase 1 planning artefacts: already on the branch.
bff stream: contributes the new current-system/functional/reference-data/item/amazon-bff-api.md reference page (BFF route input/output/error contract).
operator stream: contributes the runbook at process/sre/runbooks/amazon-creators-api-onboarding.md.
Phase 3 deployment artefacts: this directory’s 3-deployment/deployment-plan.md.

A single documentation PR carries all of these. Each stream’s contribution is reviewable as separate commits within the same PR.

Phase 3 — deployment

Deployment requires all four streams plus the operator action (Account Holder populating 1Password vaults). The hard ordering constraint is:

The operator must populate the Amazon Creators API entry in all four 1Password vaults (Arda-DemoOAM, Arda-DevOAM, Arda-StageOAM, Arda-ProdOAM) before the infrastructure PR merges. Once infrastructure merges, every subsequent amm.sh run for any partition op reads those entries; missing entries cause set -eu to abort and block all infra deploys for that partition.

bff and item-module PRs can land in any order before or after infrastructure. They are deployed via their own pipelines (Amplify build for arda-frontend-app; the operations build for operations); neither affects the other.

The recommended deploy sequence and the per-partition rollout order (dev → stage → demo → prod) are recorded in 3-deployment/deployment-plan.md, alongside the smoke-test script that exercises the route on each partition once all streams are in place.

Linear tracking

Project umbrella: PDEV-445 — Create Item from Amazon URL.
Technical subticket (this work): PDEV-446 — owns the four streams and deployment.
Deferred sibling: PDEV-429 — Order From Amazon, out of scope for v1.
Separate workstream: PDEV-439 — flaky e2e auth setup, not blocking.