[AWS] Story 1: CDK Foundation & Project Setup

[mfittko]

Problem Statement

Downstream AWS stories need a reusable CDK baseline and a deterministic
configuration contract for secrets, parameters, and provider config.

Scope

In scope:

• CDK TypeScript project structure
• Baseline VPC support and VPC import mode
• Secrets Manager and SSM parameter model
• Config CLI for set, get, list, and upload flows

Out of scope:

• Production traffic cutover
• Full runtime scaling behavior
• Final networking and edge routing

Technical Approach

• Create the infra/ CDK app and baseline stack.
• Define stack props for environment and VPC mode.
• Implement config constructs for secrets and parameters.
• Implement CLI workflows for config and API provider YAML upload.

Dependencies

Hard dependencies:

• Release workflow contract
  Blocks:
• Data layer
• Compute layer
• Networking layer
• Observability layer
• CI/CD pipeline

Acceptance Criteria

• cdk synth generates valid CloudFormation
• cdk deploy creates VPC, secrets, and SSM parameters
• CLI wrapper can set/get all secrets and config
• API providers YAML uploadable to SSM
• api_providers.example.yaml committed as template
• api_providers.yaml gitignored
• Existing VPC can be imported via props
• All configuration documented in README

Proposed Definition Of Done

• New-VPC deploy evidence is attached.
• Existing-VPC deploy evidence is attached.
• CLI positive and negative path logs are attached.
• README and operator docs are merged.

Validation Plan

1. Run synth and deploy with a newly created VPC.
2. Run synth and deploy with an imported VPC.
3. Run the CLI key matrix for secrets and params.
4. Upload and fetch API provider YAML from SSM.

Risks And Mitigations

• Risk: Ambiguous split between secrets and params.
  • Mitigation: Keep one explicit mapping table in docs and code.
• Risk: Imported VPC assumptions vary by account.
  • Mitigation: Validate one import-mode deployment before closing.

Handoff Notes

Outputs from this story are the contract for the data and compute stories.

AC/DoD Coverage Matrix

Item	Type (AC/DoD/Non-goal)	Status (Met/Partial/Unmet/Unverified)	Evidence (spec/tests/behavior)	Notes
cdk synth generates valid CloudFormation	AC	Unverified	Synth logs	Source AC
cdk deploy creates VPC, secrets, and SSM parameters	AC	Unverified	Deploy logs	Source AC
CLI wrapper can set/get all secrets and config	AC	Unverified	CLI matrix logs	Source AC
API providers YAML uploadable to SSM	AC	Unverified	Upload/fetch logs	Source AC
api_providers.example.yaml committed as template	AC	Unverified	Repo diff	Source AC
api_providers.yaml gitignored	AC	Unverified	Repo diff	Source AC
Existing VPC can be imported via props	AC	Unverified	Import deploy logs	Source AC
All configuration documented in README	AC	Unverified	README update	Source AC
New-VPC deploy evidence is attached.	DoD	Unverified	Issue evidence	Proposed DoD
Existing-VPC deploy evidence is attached.	DoD	Unverified	Issue evidence	Proposed DoD
CLI positive and negative path logs are attached.	DoD	Unverified	Issue evidence	Proposed DoD
README and operator docs are merged.	DoD	Unverified	Docs diff	Proposed DoD

[mfittko]

Refinement update applied. This issue now has explicit scope, hard dependencies, measurable acceptance criteria, a proposed Definition of Done, a validation plan, and an AC/DoD coverage matrix so it is ready for assignment.