Feature/stack architecture simplification

.claude/skills/cdk-infrastructure/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cdk-infrastructure
-description: AWS CDK infrastructure development with TypeScript. Use when creating or modifying CDK stacks, constructs, DynamoDB tables, ECS/Fargate services, Lambda functions, S3 buckets, networking, IAM roles, or any CloudFormation resources. Covers configuration patterns, cross-stack references via SSM, naming conventions, and Bedrock AgentCore integration.
+description: AWS CDK infrastructure development with TypeScript. Use when creating or modifying CDK constructs, DynamoDB tables, ECS/Fargate services, Lambda functions, S3 buckets, networking, IAM roles, or any CloudFormation resources. Covers configuration patterns, single-stack architecture, naming conventions, and Bedrock AgentCore integration.
 ---
 
 # AWS CDK Infrastructure Best Practices
@@ -11,41 +11,47 @@ description: AWS CDK infrastructure development with TypeScript. Use when creati
 - Import from `aws-cdk-lib` and `constructs`
 - Use L2 constructs when available, L1 (Cfn*) when necessary
 
-## Stack Organization
+## Architecture — Single Stack
+
+The entire application is provisioned by **one CDK stack** (`PlatformStack`). Application code is shipped out-of-band via AWS APIs (ECR push → ECS service update / Lambda code update / AgentCore Runtime update).
 
 ```
 infrastructure/
-├── bin/infrastructure.ts          # App entrypoint
+├── bin/infrastructure.ts          # App entrypoint (instantiates PlatformStack)
 ├── lib/
-│   ├── config.ts                  # Configuration loader
-│   ├── infrastructure-stack.ts    # Network resources (deploy first)
-│   ├── app-api-stack.ts           # Backend services
-│   └── my-new-stack.ts            # New stacks go here
-└── cdk.context.json               # Configuration
+│   ├── platform-stack.ts          # The one stack — all infrastructure
+│   ├── config.ts                  # Configuration loader & validator
+│   └── constructs/                # 39 reusable CDK constructs
+│       ├── network/               # VPC, ALB, ECS cluster
+│       ├── identity/              # Cognito, secrets, KMS, OAuth
+│       ├── data/                  # DynamoDB tables, file uploads
+│       ├── rag/                   # RAG documents, vectors
+│       ├── rag-ingestion/         # RAG ingestion Lambda
+│       ├── artifacts/             # Artifact rendering pipeline
+│       ├── mcp-sandbox/           # MCP Apps sandbox proxy
+│       ├── agentcore/             # Memory, Code Interpreter, Browser, Gateway
+│       ├── inference-api/         # AgentCore Runtime
+│       ├── app-api/               # Fargate service
+│       ├── fine-tuning/           # SageMaker IAM
+│       ├── spa/                   # SPA CloudFront distribution
+│       └── zones/                 # Route53, ALB DNS
+└── cdk.context.json               # Configuration defaults
 ```
 
-**Deployment Order:**
-1. `InfrastructureStack` - VPC, ALB, ECS Cluster (always first)
-2. Other stacks import network resources via SSM
+**Key principle:** CDK deploys are rare (infrastructure changes only). Day-to-day code changes deploy via `backend.yml` (AWS API calls, no CDK).
 
 ## Configuration
 
 Use the centralized config system:
 
 ```typescript
 import { loadConfig, getResourceName, getStackEnv, applyStandardTags } from './config';
+```
 
-export class MyStack extends cdk.Stack {
-  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
-    const config = loadConfig(scope);
-    super(scope, id, {
-      ...props,
-      env: getStackEnv(config),
-      stackName: getResourceName(config, 'my-stack'),
-    });
-    applyStandardTags(this, config);
-  }
-}
+PlatformStack receives config via props:
+```typescript
+const config = loadConfig(app);
+new PlatformStack(app, `${config.projectPrefix}-PlatformStack`, { config, env });
 ```
 
 For configuration patterns, see [references/configuration.md](references/configuration.md).
@@ -57,31 +63,25 @@ For configuration patterns, see [references/configuration.md](references/configu
 getResourceName(config, 'user-quotas')  // "bsu-agentcore-user-quotas"
 ```
 
-**SSM Parameters:** Hierarchical naming:
+**SSM Parameters:** Hierarchical naming for runtime consumption:
 ```
 /{projectPrefix}/{category}/{resource-type}
 ```
 
-Categories: `/network/`, `/quota/`, `/cost-tracking/`, `/auth/`, `/frontend/`, `/gateway/`
+Categories: `/network/`, `/quota/`, `/cost-tracking/`, `/auth/`, `/frontend/`, `/gateway/`, `/rag/`, `/artifacts/`
 
-## Cross-Stack References
+## Cross-Construct References
 
-**Export:**
-```typescript
-new ssm.StringParameter(this, 'VpcIdParam', {
-  parameterName: `/${config.projectPrefix}/network/vpc-id`,
-  stringValue: vpc.vpcId,
-});
-```
+Since everything is in one stack, use **typed props** — not SSM:
 
-**Import:**
 ```typescript
-const vpcId = ssm.StringParameter.valueForStringParameter(
-  this,
-  `/${config.projectPrefix}/network/vpc-id`
-);
+// In PlatformStack:
+const network = new NetworkConstruct(this, 'Network', { config });
+new AlbConstruct(this, 'Alb', { config, vpc: network.vpc });
 ```
 
+SSM parameters are published **only for runtime consumption** by ECS tasks and Lambdas — never for CDK-to-CDK references within the same stack.
+
 ## DynamoDB Tables
 
 - Always use PK + SK for flexibility
@@ -93,10 +93,11 @@ For table patterns, see [references/dynamodb.md](references/dynamodb.md).
 
 ## ECS/Fargate
 
-- Import cluster from SSM
+- Cluster created by NetworkConstruct, referenced via typed prop
 - Health checks mandatory
 - Auto-scaling with CPU/memory targets
 - Circuit breaker for rollback
+- Bootstrap container pattern: CDK creates the service with a placeholder image; the backend workflow pushes the real image via `update-service`
 
 For service patterns, see [references/ecs-fargate.md](references/ecs-fargate.md).
 
@@ -105,6 +106,7 @@ For service patterns, see [references/ecs-fargate.md](references/ecs-fargate.md)
 - Use ARM64 architecture (cost optimization)
 - Role with least privilege
 - Secrets Manager access requires wildcard suffix
+- Bootstrap pattern: CDK creates the function with placeholder code; the backend workflow pushes real code via `update-function-code`
 
 For Lambda patterns, see [references/lambda.md](references/lambda.md).
 
@@ -138,19 +140,17 @@ name: getResourceName(config, 'memory').replace(/-/g, '_')
 resources: [`${secret.secretArn}*`]
 ```
 
-**Environment Removal Policy:**
+**Removal Policy:**
 ```typescript
-removalPolicy: config.environment === 'prod'
-  ? cdk.RemovalPolicy.RETAIN
-  : cdk.RemovalPolicy.DESTROY
+removalPolicy: getRemovalPolicy(config)  // RETAIN in prod, DESTROY in dev
 ```
 
 ## CDK Commands
 
 ```bash
 cd infrastructure
-npm install           # Install dependencies
+npm ci                # Install dependencies
 npx cdk synth         # Synthesize CloudFormation
-npx cdk deploy --all  # Deploy all stacks
+npx cdk deploy {prefix}-PlatformStack  # Deploy
 npx cdk diff          # Preview changes
 ```

.github/README-ACTIONS.md

@@ -6,19 +6,60 @@ Deploy a production-ready multi-agent AI platform to your AWS account in about 4
 >
 > ### 👉 [Start here — Step 1: Prerequisites](./docs/deploy/step-01-prerequisites.md)
 
+## Architecture Overview
+
+The platform uses a **single-stack architecture**:
+
+- **One CDK stack** (`PlatformStack`) provisions all AWS infrastructure — VPC, ALB, DynamoDB, S3, Cognito, CloudFront, AgentCore, ECS, Lambdas.
+- **Application code ships out-of-band** via AWS APIs — not via CDK deploys. This means infrastructure changes (rare) and code changes (frequent) are completely decoupled.
+
 ## What You'll Deploy
 
+### Infrastructure (via `platform.yml`)
+
 | Component | Description |
 |-----------|-------------|
 | **VPC + ALB + ECS** | Networking, load balancer, and container orchestration |
-| **Fine-Tuning** *(optional)* | SageMaker training/inference infrastructure, S3 artifact storage, DynamoDB job tracking |
-| **Artifacts** *(optional)* | Iframe-isolated artifact rendering (DDB metadata, S3 content, CloudFront at `artifacts.{domain}`, Lambda render service) |
-| **RAG Ingestion** | Document ingestion pipeline for retrieval-augmented generation |
-| **Inference API** | Strands Agent runtime powered by AWS Bedrock AgentCore |
-| **App API** | Backend REST API for chat, sessions, admin, and auth |
-| **Frontend** | Angular SPA served via CloudFront CDN |
-| **Gateway** | Lambda-based MCP tool endpoints (Wikipedia, ArXiv, Finance, etc.) |
-| **Bootstrap Data** | Auth provider config, default models, roles, and tools |
+| **DynamoDB** | ~24 tables for all application state |
+| **S3** | 6 buckets (file uploads, RAG, artifacts, SPA, MCP sandbox, fine-tuning) |
+| **Cognito** | User pool, identity providers, BFF app client |
+| **CloudFront** | SPA distribution + artifacts iframe origin + MCP sandbox proxy |
+| **AgentCore** | Memory, Code Interpreter, Browser, Gateway, Runtime |
+| **SageMaker IAM** | Execution role for fine-tuning jobs |
+
+### Application Code (via `backend.yml`)
+
+| Service | Deploy Method |
+|---------|--------------|
+| **App API** | ECR push → ECS service update |
+| **Inference API** | ECR push → AgentCore Runtime update |
+| **RAG Ingestion** | ECR push → Lambda update-function-code |
+| **Artifact Render** | Zip → Lambda update-function-code |
+
+### Frontend (via `frontend-deploy.yml`)
+
+| Component | Deploy Method |
+|-----------|--------------|
+| **Angular SPA** | S3 sync + CloudFront invalidation |
+
+### Bootstrap Data (via `bootstrap-data-seeding.yml`)
+
+| Component | Description |
+|-----------|-------------|
+| **Seed data** | Auth provider config, default models, roles, and tools |
+
+---
+
+## Workflows
+
+| Workflow | Trigger | What it does |
+|---------|---------|--------------|
+| `platform.yml` | Infra code changes / manual | `cdk deploy` — provisions or updates all AWS resources |
+| `backend.yml` | Backend code changes / manual | Builds Docker images (content-hash skip), pushes to ECR, updates ECS/Lambda/Runtime |
+| `frontend-deploy.yml` | Frontend code changes / manual | Builds Angular SPA, syncs to S3, invalidates CloudFront |
+| `bootstrap-data-seeding.yml` | Manual | Seeds DynamoDB with default config (first deploy only) |
+| `teardown.yml` | Manual | Destroys all CDK stacks (for cleanup) |
+| `nightly-deploy-pipeline.yml` | Nightly / manual | Full end-to-end: platform → backend → frontend |
 
 ---
 
@@ -39,6 +80,29 @@ Follow each step in order. Click a step to open its guide.
 
 ---
 
+## Deploy Order (First Time)
+
+```
+1. platform.yml          → provisions all AWS infrastructure (~15 min)
+2. backend.yml           → builds + deploys all container images (~5 min)
+3. frontend-deploy.yml   → builds + deploys the Angular SPA (~2 min)
+4. bootstrap-data-seeding.yml → seeds default config data (~1 min)
+```
+
+After the first deploy, `platform.yml` only needs to run when infrastructure changes. Day-to-day pushes trigger `backend.yml` and/or `frontend-deploy.yml` automatically.
+
+---
+
+## Content-Hash Docker Builds
+
+The `backend.yml` workflow uses **content-hash tagging** — each image is tagged with a SHA-256 hash of its source inputs (Dockerfile + source tree + dependency manifests). If ECR already has an image with that tag, the build is skipped entirely. This means:
+
+- Pushing a frontend-only change doesn't rebuild any Docker images
+- Pushing a change to one service only rebuilds that service's image
+- Unchanged services deploy in seconds (just verifies the tag exists)
+
+---
+
 ## Quick Links
 
 - [Troubleshooting](./docs/deploy/troubleshooting.md) — common issues and fixes

.github/actions/build-and-push-image/action.yml

@@ -0,0 +1,52 @@
+name: 'Build and push ECR image'
+description: |
+  Run scripts/build/build-one.sh for one of the project's images,
+  with conditional QEMU + buildx setup for arm64 builds (AgentCore
+  Runtime). Wraps the configure-aws-credentials composite + the
+  build script call so per-image jobs in backend.yml stay short.
+inputs:
+  image-name:
+    description: 'Image to build (app-api, inference-api, rag-ingestion)'
+    required: true
+  platform:
+    description: 'Build platform (linux/amd64 or linux/arm64). arm64 sets up QEMU + buildx.'
+    required: false
+    default: 'linux/amd64'
+  aws-region:
+    description: 'AWS region for ECR push'
+    required: true
+  aws-role-arn:
+    description: 'AWS role ARN for OIDC auth (preferred)'
+    required: false
+  aws-access-key-id:
+    description: 'AWS access key ID fallback'
+    required: false
+  aws-secret-access-key:
+    description: 'AWS secret access key fallback'
+    required: false
+outputs:
+  image_tag:
+    description: 'Content-hash image tag pushed to ECR'
+    value: ${{ steps.build.outputs.image_tag }}
+runs:
+  using: 'composite'
+  steps:
+    - uses: ./.github/actions/configure-aws-credentials
+      with:
+        aws-region: ${{ inputs.aws-region }}
+        aws-role-arn: ${{ inputs.aws-role-arn }}
+        aws-access-key-id: ${{ inputs.aws-access-key-id }}
+        aws-secret-access-key: ${{ inputs.aws-secret-access-key }}
+    # Inference API runs on AgentCore Runtime (linux/arm64). On the
+    # amd64 GitHub-hosted runner we need QEMU + buildx emulation so
+    # `docker build --platform linux/arm64` works.
+    - if: inputs.platform == 'linux/arm64'
+      uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
+      with:
+        platforms: arm64
+    - if: inputs.platform == 'linux/arm64'
+      uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+    - name: Build & push ${{ inputs.image-name }}
+      id: build
+      shell: bash
+      run: bash scripts/build/build-one.sh ${{ inputs.image-name }}

.github/copilot-instructions.md

@@ -28,17 +28,18 @@ npx eslint src/ && npx prettier --check src/
 
 ### Infrastructure (`cd infrastructure`)
 ```bash
-npm ci && npm run build
-npx cdk synth                          # validates stacks
-npx cdk deploy --all
-npm test -- test/stack-dependencies.test.ts   # verifies new stacks are registered
+npm ci && npx tsc --noEmit
+npx jest                                          # CDK construct + stack tests
+npx cdk synth                                     # validates the stack
+npx cdk deploy {prefix}-PlatformStack             # deploy the single stack
 ```
 
 ## Architecture — the big picture
 
 - **Three independent backend consumers** of `apis.shared`: `app_api`, `inference_api`, and `agents/`. They must **never import from each other** — only from `apis.shared`. Enforced by `backend/tests/architecture/test_import_boundaries.py`.
 - **Inference API runs inside an AgentCore Runtime container.** The runtime data plane only proxies `POST /invocations` and `GET /ping` — any other route returns 404 in cloud (works locally because `localhost:8001` bypasses the gateway). User-facing CRUD endpoints **belong in app-api**, not inference-api. To get workload context on app-api, use the `AGENTCORE_RUNTIME_WORKLOAD_NAME` mint fallback in `apis/shared/oauth/agentcore_identity.py`.
-- **Deploy order** (cross-stack SSM references): Infrastructure → (Gateway, RAG Ingestion, SageMaker Fine-Tuning, Artifacts, MCP Sandbox in parallel) → Inference API → App API → Frontend. App API reads `runtime-workload-identity-name` from SSM, published by Inference API.
+- **Single CDK stack.** All AWS resources live in one `PlatformStack` (`infrastructure/lib/platform-stack.ts`). No cross-stack SSM references between CDK stacks; values that flow between constructs go through the typed `PlatformComputeRefs` interface.
+- **Deploy order:** `platform.yml` (CDK, only when infra changes) → `backend.yml` (per-image build + AWS-API code deploy: app-api, inference-api, rag-ingestion, artifact-render in parallel) → `frontend-deploy.yml` (S3 sync + CloudFront invalidation). Day-to-day code changes only re-run `backend.yml`. Compute image URIs are read from SSM at CFN deploy time (`/{prefix}/app-api/image-tag`, `/{prefix}/inference-api/image-tag`) so any task-def or Runtime property change picks up whatever image the build pipeline most recently pushed.
 - **Errors stream as assistant messages over SSE**, not HTTP error codes. See SSE event table in `CLAUDE.MD` (`message_start`, `content_block_*`, `tool_use`/`tool_result`, `ui_resource`, `stream_error`, `oauth_required`, `compaction`, `done`).
 - **Multi-protocol tools:** direct/AWS-SDK tools live in `agents/main_agent/tools/`; remote tools come via MCP+SigV4 (Gateway Lambda) or A2A (Runtime). A2A is currently **client-only**; if exposing an A2A server, `capabilities` must include `streaming=True` or clients hang.
 - **Frontend is signal-based** throughout (`signal()`, `computed()`). API shapes are defined by backend routes; matching TS interfaces must be updated in the same PR as breaking backend changes.
@@ -63,7 +64,7 @@ npm test -- test/stack-dependencies.test.ts   # verifies new stacks are register
 | Shared backend code | `backend/src/apis/shared/<domain>/` |
 | Lambda for an infra stack | `backend/src/lambdas/<lambda-name>/` (not part of `apis/` boundary) |
 | Angular page | `frontend/ai.client/src/app/<feature>/` |
-| New CDK stack | `infrastructure/lib/<stack-name>-stack.ts` — also register in `test/stack-dependencies.test.ts` with a tier, add `scripts/stack-<name>/`, add a workflow under `.github/workflows/`, update `.github/docs/deploy/step-04-deploy.md` |
+| New CDK construct | `infrastructure/lib/constructs/<area>/<name>-construct.ts` — compose into `PlatformStack` (`lib/platform-stack.ts`); if it exposes values to compute constructs, thread them through `PlatformComputeRefs` rather than SSM. There are no separate CDK *stacks* anymore. |
 
 ## Debugging cheatsheet