Skip to the content.

SAM infrastructure (test / production)

API Gateway HTTP API → Nitro aws_lambda (nodejs24.x) → DynamoDB, plus CDN for hashed static assets (NUXT_APP_CDN_URL).

Test CDN: shared Example Organization/portfolio stack shared-cdn-test (https://cdn.example.com, bucket shared-cdn-test-assets-000000000000, sync without --delete). See shared CDN note below.

Production CDN: stack-owned private S3 + CloudFront (OAC) until a shared production cutover is requested.

Operations (install SAM CLI, deploy, Windows notes): infra/sam/README.md

CI/CD: cicd.md · CDN behavior: web/features/cdn-guide.md · Dry-run public sync: npm run sam:sync:dryrun / --shared

Layout

Path Role
infra/sam/template.yaml Lambda, HTTP API, DynamoDB, S3, CloudFront
infra/sam/samconfig.toml test / prod profiles
infra/sam/.aws-sam/build-src/server Staged Nitro server (Lambda CodeUri)
infra/sam/.aws-sam/build-src/public Staged .output/public (S3 sync / CDN)

Website HTML/API and CDN assets do not share a host: pages hit execute-api; hashed files and favicon.ico hit *.cloudfront.net. Lambda does not ship .output/public (nitro.serveStatic: false on aws_lambda). SAM stages build-src/server (CodeUri) and build-src/public (S3 sync) separately; GET/HEAD for static extensions on the API host 302 to the CDN origin.

Shared test CDN (Example Organization + portfolio)

Cutover (2026-08-21): test NUXT_APP_CDN_URL / sync target is the shared CloudFormation stack owned in Example Organization (infra/sam/shared-cdn.yaml). No per-project prefix. Do not destroy shared-cdn-test from this repo. Do not aws s3 sync --delete that bucket. Production stays on portfolio-prod CDN.

Historical agent brief: agents/shared-cdn-handoff.md.

Hardening and custom domain

Media library (DAM)

SAM also provisions Media DynamoDB (MediaTable), SQS (+ DLQ), and MediaWorkerFunction (@tgmc/media-aws worker). Blobs live under the media/ prefix on AssetsBucket today (catalog blobs move to m/{tenant}/{kind}/{name}.{ext}; the public-asset sync never uploads, --deletes or metadata-repairs m/, media/ or pending/ (presigned uploads waiting for complete), and never --deletes the legacy site media dirs i/, v/, d/; see cicd.md § No media work in GitHub Actions); optional CloudFront invalidation on delete uses ASSETS_DISTRIBUTION_ID (every cached version of a key: /m/…/hero.png*). Versioned media URLs: media URLs carry ?v=<content hash> (media § Versioned public URLs); AssetsDistribution has an m/* cache behaviour with MediaCachePolicy (CachingOptimized settings with the v query string, and only it, in the cache key; MaxTTL one year), so a replaced object’s new URL never hits the stale copy while objects keep immutable for a year. Other paths keep the managed CachingOptimized policy (no query strings). Nitro web serves Bearer-protected /api/media/* via @tgmc/media-nuxt (MEDIA_TABLE, ASSETS_BUCKET, MEDIA_QUEUE_URL, ADMIN_TOKEN). Media URLs use MEDIA_PUBLIC_BASE_URL, which the template sets on NitroFunction to the stack’s own distribution (https://${AssetsDistribution.DomainName}) on test and production: on test, NUXT_APP_CDN_URL is the shared CDN, which does not front this stack’s AssetsBucket, so media URLs built from it would 404. The worker builds no URLs and does not get it. On Lambda the media library is always DynamoDB + S3, whatever DATA_BACKEND resolves. Details: packages/media-aws.md, packages/media-nuxt.md.

Pending uploads. Presigned media PUTs land under pending/<assetId>/m/... (media § Name reservation); complete checks and sanitizes the object there, copies it to m/ and deletes it. AssetsBucketPolicy denies CloudFront s3:GetObject on pending/* (the allow on /* stays for everything else), the ExpirePendingUploads lifecycle rule expires pending/ objects (and their noncurrent versions and incomplete multipart uploads) after one day, and only NitroFunction may read, write and delete pending/* (and list that prefix, so a missing key is a 404, not a 403); the worker never touches it.

Upload triggers. AssetsBucket notifies MediaQueue of every s3:ObjectCreated:* under m/, and the worker runs the on-ingest recipes (meta + the t / 640 / 1280 / 1920 variants); complete on Lambda no longer runs them. MediaQueuePolicy admits only s3.amazonaws.com for this stack’s bucket ARN (constructed from the BucketName expression, not GetAtt) and this account; the bucket DependsOn the policy, so CloudFormation creates the policy before S3 validates the notification with an s3:TestEvent. The change is an in-place update of the retained bucket (no replacement). The worker’s SQS event is capped at 5 concurrent invocations. Existing objects are not backfilled — use Re-run processing in the admin. See media-aws § Upload triggers.

Commands

npm run sam:build
npm run sam:sync:dryrun
npm run sam:deploy:test
npm run sam:deploy:prod

Region: see samconfig.toml (currently us-west-2). GitHub CD uses OIDC (AWS_ROLE_ARN) and Environments test / production.