feat!: migrate to pnpm workspaces monorepo with Aurora DSQL and Drizzle ORM

Replace the single-package npm project with a pnpm workspaces monorepo,
migrate from Aurora Serverless v2 + Prisma to Aurora DSQL + Drizzle ORM,
and replace ESLint + Prettier with oxlint + oxfmt.

Architecture:
- apps/webapp (Next.js), apps/async-job (Lambda), apps/cdk (CDK infra)
- packages/db (Drizzle schema, DSQL client, migration runner)
- packages/shared-types (job payload Zod schemas)

Database:
- Aurora DSQL with IAM auth (no VPC, no NAT, no Bastion)
- Drizzle ORM with relations() for joins (no FK, DSQL constraint)
- Custom migration runner: hash verification, 1 DDL/tx, DSQL SQL validation
- dsql-migrator CDK Construct: Docker Lambda + CDK Trigger for deploy-time migration

Tooling:
- oxlint with type-aware linting (oxlint-tsgolint) replaces ESLint + tsc --noEmit
- oxfmt with .oxfmtrc.json matching original .prettierrc (singleQuote, printWidth 120)
- shamefully-hoist removed; missing implicit deps made explicit

Docker:
- All Dockerfiles use pnpm install (no --filter) for strict mode compatibility
- esbuild bundles to .mjs (Lambda ESM requirement)
- IgnoreMode.DOCKER on all Docker assets to read root .dockerignore
- Verified: all 3 images build and respond to Lambda RIE invocations

Refs: #98, #91, discussion #94

Author: konokenj

.dockerignore

@@ -0,0 +1,20 @@
+# dependencies (reinstalled inside container)
+**/node_modules
+
+# build artifacts
+**/.next
+apps/cdk/cdk.out
+apps/cdk/.cdk.staging
+
+# vcs / ci / editor
+.git
+.github
+.kiro
+.playwright-cli
+
+# docs / meta
+.serverless-full-stack-webapp-starter-kit
+scripts
+*.md
+LICENSE
+CHANGELOG.md

.github/workflows/build.yml

@@ -8,39 +8,23 @@ on:
   workflow_dispatch:
   pull_request:
 jobs:
-  Build-and-Test-CDK:
+  Build-and-Test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
       - name: Use Node.js
         uses: actions/setup-node@v6
         with:
           node-version: '22.x'
-      - run: |
-          npm ci
-          npm run format:check
-        working-directory: ./cdk
-        name: Install dependencies and run static analysis
-      - run: |
-          npm run build
-          npm run test
-        working-directory: ./cdk
-        name: build and test
-  Build-and-Test-Webapp:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v5
-      - name: Use Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: '22.x'
-      - run: |
-          npm ci
-          npm run format:check
-        working-directory: ./webapp
-        name: Install dependencies and run static analysis
-      - run: |
-          cp .env.local.example .env.local
-          npm run build
-        working-directory: ./webapp
-        name: build
+      - name: Install pnpm
+        run: corepack enable && corepack prepare pnpm@10.8.1 --activate
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Check
+        run: pnpm run check:ci
+      - name: Test
+        run: pnpm run test:unit
+      - name: Build
+        run: |
+          cp apps/webapp/.env.local.example apps/webapp/.env.local
+          pnpm run build

.github/workflows/update_snapshot.yml

@@ -25,12 +25,13 @@ jobs:
         uses: actions/setup-node@v6
         with:
           node-version: "22.x"
+      - name: Install pnpm
+        run: corepack enable && corepack prepare pnpm@10.8.1 --activate
       - run: |
-          npm ci
-          npm run test -- -u
-        working-directory: ./cdk
+          pnpm install --frozen-lockfile
+          cd apps/cdk && pnpm run test:unit -u
       - name: Add & Commit
         uses: EndBug/add-and-commit@v7.2.0
         with:
-          add: "cdk/test/__snapshots__/."
+          add: "apps/cdk/test/__snapshots__/."
           message: "update snapshot"

.gitignore

@@ -0,0 +1,30 @@
+node_modules
+.DS_Store
+*.pem
+*.tsbuildinfo
+*.bkp
+
+# env files
+.env*
+!.env.local.example
+!.env.credentials
+
+# next.js
+.next
+out
+
+# cdk
+cdk.out
+.cdk.staging
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+.pnpm-debug.log*
+
+# generated
+dist
+
+# dev tools
+.kiro/settings/
+.playwright-cli/

.oxfmtrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "semi": true,
+  "singleQuote": true,
+  "printWidth": 120
+}

.prettierrc

@@ -13,7 +13,7 @@ As an aws-samples project:
 - Correctness is the top priority — users learn patterns from this code.
 - Reproducibility — following the README must produce a working deployment.
 - Readability — code should be understandable by developers new to serverless.
-- One-command deploy — `npx cdk deploy --all` must be the only deployment step.
+- One-command deploy — `pnpm exec cdk deploy --all` must be the only deployment step.
 
 The litmus test for any PR: "After this merges, will a developer who copies the kit build their app on a correct understanding?"
 
@@ -41,12 +41,14 @@ The litmus test for any PR: "After this merges, will a developer who copies the
 
 | Choice | Rationale |
 |--------|-----------|
-| `prisma db push` over `prisma migrate` | Simpler default for starter-kit scope. Users can switch to `prisma migrate` when they need migration history. |
-| NAT Instance over NAT Gateway | ~$30/month savings. Acceptable trade-off for a starter kit. |
+| Aurora DSQL over Aurora Serverless v2 | No VPC required, true pay-per-request, IAM authentication. Eliminates NAT Instance cost and VPC complexity. |
+| Drizzle ORM over Prisma | Pure TypeScript (no `prisma generate`), `relations()` naturally fits DSQL's no-FK constraint, simpler monorepo sharing. |
+| Custom migration runner over `drizzle-kit push` | DSQL requires 1 DDL per transaction. The runner splits SQL on blank lines and validates DSQL compatibility before execution. |
 | Single Lambda for all async jobs | Reduces cold starts and simplifies deployment. `cmd` parameter selects the entry point. |
 | `proxy.ts` over Next.js middleware | Runs inside Lambda handler, avoiding cold-start CPU starvation from JWKS fetch in middleware. |
 | `output: 'standalone'` | Required for Lambda deployment via Docker image. |
 | Lambda Web Adapter | Enables response streaming with CloudFront + Lambda Function URL. |
+| oxlint + oxfmt over ESLint + Prettier | Faster linting and formatting. Type-aware linting via oxlint-tsgolint replaces `tsc --noEmit`. |
 
 ### Architecture Decision Records (ADR)
 

.serverless-full-stack-webapp-starter-kit/design/DESIGN_PRINCIPLES.md

@@ -0,0 +1,87 @@
+<mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/29.0.3 Chrome/140.0.7339.249 Electron/38.7.0 Safari/537.36" version="29.0.3">
+  <diagram name="Architecture" id="arch">
+    <mxGraphModel dx="1018" dy="1149" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="1100" pageHeight="800" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="g1" value="Webapp" style="rounded=1;whiteSpace=wrap;fillColor=#E8F5E9;strokeColor=#388E3C;fontSize=16;fontStyle=1;verticalAlign=top;spacingTop=8;arcSize=8;" parent="1" vertex="1">
+          <mxGeometry x="160" y="-30" width="420" height="310" as="geometry" />
+        </mxCell>
+        <mxCell id="g2" value="Authentication" style="rounded=1;whiteSpace=wrap;fillColor=#FFF3E0;strokeColor=#F57C00;fontSize=16;fontStyle=1;verticalAlign=top;spacingTop=8;arcSize=8;" parent="1" vertex="1">
+          <mxGeometry x="590" y="-30" width="200" height="150" as="geometry" />
+        </mxCell>
+        <mxCell id="g3" value="Database" style="rounded=1;whiteSpace=wrap;fillColor=#FFF8E1;strokeColor=#FBC02D;fontSize=16;fontStyle=1;verticalAlign=top;spacingTop=8;arcSize=8;" parent="1" vertex="1">
+          <mxGeometry x="590" y="130" width="200" height="150" as="geometry" />
+        </mxCell>
+        <mxCell id="g4" value="Asynchronous Job" style="rounded=1;whiteSpace=wrap;fillColor=#FCE4EC;strokeColor=#E91E63;fontSize=16;fontStyle=1;verticalAlign=top;spacingTop=8;arcSize=8;" parent="1" vertex="1">
+          <mxGeometry x="160" y="290" width="420" height="160" as="geometry" />
+        </mxCell>
+        <mxCell id="g5" value="Scheduled Job" style="rounded=1;whiteSpace=wrap;fillColor=#F3E5F5;strokeColor=#9C27B0;fontSize=16;fontStyle=1;verticalAlign=top;spacingTop=8;arcSize=8;" parent="1" vertex="1">
+          <mxGeometry x="590" y="290" width="200" height="160" as="geometry" />
+        </mxCell>
+        <mxCell id="e1" value="Send Requests" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;fontSize=13;labelBackgroundColor=default;spacing=2;" parent="1" source="users" target="cf" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="e2" value="Lambda Function URL" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;fontSize=13;verticalAlign=bottom;labelBackgroundColor=none;spacing=2;" parent="1" source="cf" target="nextjs" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="e5" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;exitX=1;exitY=0.5;entryX=0;entryY=0.5;" parent="1" source="nextjs" target="dsql" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="e6" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;dashed=1;exitX=0.5;exitY=1;entryX=0.5;entryY=0;fontSize=13;labelBackgroundColor=default;spacing=2;" parent="1" source="nextjs" target="jobhandler" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="e7" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" parent="1" source="jobhandler" target="appsync" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="e8" value="Real-time&#xa;Notification" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;dashed=1;exitX=0;exitY=0.5;fontSize=13;labelBackgroundColor=default;spacing=2;" parent="1" source="appsync" target="users" edge="1">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="50" y="260" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="e9" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;dashed=1;exitX=0;exitY=0.5;entryX=1;entryY=0.5;" parent="1" source="eb" target="jobhandler" edge="1">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="users" value="Users" style="sketch=0;outlineConnect=0;fontColor=#232F3E;gradientColor=none;strokeColor=none;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=13;fontStyle=1;aspect=fixed;pointerEvents=1;shape=mxgraph.aws4.users;fillColor=#232F3D;" parent="1" vertex="1">
+          <mxGeometry x="50" y="170" width="60" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="YBvlDhobisiv5zPTTUV7-2" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.308;entryY=1.025;entryDx=0;entryDy=0;entryPerimeter=0;edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="cf" target="gEdge">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="cf" value="CloudFront" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=14;fontStyle=1;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.cloudfront;fillColor=#8C4FFF;" parent="1" vertex="1">
+          <mxGeometry x="230" y="170" width="60" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="nextjs" value="Next.js&#xa;Lambda Web Adapter" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=14;fontStyle=1;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda;fillColor=#ED7100;" parent="1" vertex="1">
+          <mxGeometry x="450" y="170" width="60" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="cognito" value="&lt;span&gt;Cognito&lt;/span&gt;&lt;br&gt;User Pool" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=14;fontStyle=1;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.cognito;fillColor=#DD344C;" parent="1" vertex="1">
+          <mxGeometry x="660" y="10" width="60" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="dsql" value="Aurora DSQL" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=14;fontStyle=1;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.aurora;fillColor=#C925D1;" parent="1" vertex="1">
+          <mxGeometry x="660" y="170" width="60" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="appsync" value="AppSync Events" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=14;fontStyle=1;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.appsync;fillColor=#E7157B;" parent="1" vertex="1">
+          <mxGeometry x="230" y="330" width="60" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="jobhandler" value="Job Handler" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=14;fontStyle=1;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.lambda;fillColor=#ED7100;" parent="1" vertex="1">
+          <mxGeometry x="450" y="330" width="60" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="eb" value="EventBridge&#xa;Scheduler" style="sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=14;fontStyle=1;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.eventbridge;fillColor=#E7157B;" parent="1" vertex="1">
+          <mxGeometry x="660" y="330" width="60" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="YBvlDhobisiv5zPTTUV7-1" value="" style="group" vertex="1" connectable="0" parent="1">
+          <mxGeometry x="184" y="30" width="250" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="gEdge" value="" style="rounded=1;whiteSpace=wrap;fillColor=none;strokeColor=#ED7100;fontSize=10;arcSize=12;" vertex="1" parent="YBvlDhobisiv5zPTTUV7-1">
+          <mxGeometry x="-1" width="250" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="edge" value="&lt;b&gt;Lambda@Edge&lt;br&gt;&lt;/b&gt;&amp;nbsp; SigV4 Request Signer" style="sketch=0;outlineConnect=0;fontColor=#232F3E;gradientColor=none;strokeColor=none;dashed=0;verticalLabelPosition=middle;labelPosition=right;verticalAlign=middle;align=left;html=1;fontSize=14;fontStyle=0;aspect=fixed;pointerEvents=1;shape=mxgraph.aws4.lambda;fillColor=#ED7100;spacing=6;" parent="YBvlDhobisiv5zPTTUV7-1" vertex="1">
+          <mxGeometry x="10" y="7" width="28" height="28" as="geometry" />
+        </mxCell>
+        <mxCell id="cff" value="&lt;b&gt;CloudFront Functions&lt;br&gt;&lt;/b&gt;&amp;nbsp; Next.js Cache Header Editor" style="sketch=0;outlineConnect=0;fontColor=#232F3E;gradientColor=none;strokeColor=none;dashed=0;verticalLabelPosition=middle;labelPosition=right;verticalAlign=middle;align=left;html=1;fontSize=14;fontStyle=0;aspect=fixed;pointerEvents=1;shape=mxgraph.aws4.lambda;fillColor=#ED7100;spacing=6;" vertex="1" parent="YBvlDhobisiv5zPTTUV7-1">
+          <mxGeometry x="10" y="45" width="28" height="28" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

.serverless-full-stack-webapp-starter-kit/docs/imgs/architecture.drawio

@@ -0,0 +1,68 @@
+# v3 Migration Guide: pnpm Workspaces + DSQL + Drizzle
+
+This guide covers the major changes in v3 for users migrating from v2.
+
+## Breaking changes
+
+### 1. Package manager: npm → pnpm workspaces
+
+The project is now a pnpm monorepo. All `npm` commands should be replaced with `pnpm`.
+
+- `npm ci` → `pnpm install`
+- `npm run build` → `pnpm run build`
+- `package-lock.json` → `pnpm-lock.yaml`
+
+### 2. ORM: Prisma → Drizzle
+
+Prisma has been replaced with Drizzle ORM for DSQL compatibility.
+
+Key differences:
+- No `prisma generate` step — Drizzle is pure TypeScript
+- Schema defined in `packages/db/src/schema.ts` using Drizzle's `pgTable()` API
+- Relations use `relations()` (query builder only, no SQL-level FK)
+- Zod schemas are hand-written, not generated from the ORM
+
+Migration steps for custom code:
+1. Replace `@prisma/client` imports with `@repo/db/client` and `@repo/db/schema`
+2. Replace `prisma.model.findMany()` with `db.query.model.findMany()` or `db.select().from(table)`
+3. Replace `prisma.model.create()` with `db.insert(table).values()`
+4. Replace `prisma.model.update()` with `db.update(table).set().where()`
+5. Replace `prisma.model.delete()` with `db.delete(table).where()`
+
+### 3. Database: Aurora Serverless v2 → Aurora DSQL
+
+Aurora Serverless v2 (VPC-bound) has been replaced with Aurora DSQL (VPC-free).
+
+Key differences:
+- No VPC, NAT Instance, or Bastion Host required
+- IAM authentication instead of username/password
+- DSQL constraints: no SERIAL, no FK, no JSON/JSONB, 1 DDL per transaction
+- `CREATE INDEX` must use `ASYNC` keyword
+
+### 4. VPC removal
+
+The entire VPC stack has been removed. Lambda functions connect to DSQL over the public internet with IAM authentication.
+
+### 5. Project structure
+
+```
+# v2
+webapp/          → apps/webapp/
+cdk/             → apps/cdk/
+                   apps/async-job/     (new, extracted from webapp/src/jobs/)
+                   packages/db/        (new, Drizzle schema + migration runner)
+                   packages/shared-types/ (new, job payload types)
+```
+
+### 6. Linting: ESLint + Prettier → oxlint + oxfmt
+
+ESLint and Prettier have been replaced with oxlint and oxfmt for faster linting.
+
+### 7. Docker builds in pnpm monorepo (strict mode, no shamefully-hoist)
+
+Key constraints when building Docker images from a pnpm workspace without `shamefully-hoist`:
+
+- **`pnpm install --filter` does not hoist transitive dependencies of workspace packages.** If `apps/async-job` depends on `@repo/db`, and `@repo/db` depends on `pg`, esbuild inside Docker cannot resolve `pg` from `apps/async-job/node_modules`. Use `pnpm install --frozen-lockfile` (no `--filter`) in Dockerfiles.
+- **CDK `DockerImageCode.fromImageAsset` does not read `.dockerignore` by default.** Set `ignoreMode: IgnoreMode.DOCKER` on every Docker asset whose build context is the monorepo root. Without this, `cdk.out` is recursively copied into itself, causing `ENAMETOOLONG`.
+- **esbuild `--format=esm` output requires `.mjs` extension for Lambda.** The Lambda Node.js runtime loads handlers as CommonJS unless the file has `.mjs` extension or a `package.json` with `"type": "module"` exists in `/var/task`.
+- **`@aws/*` ≠ `@aws-sdk/*`.** `--external:@aws-sdk/*` does not exclude `@aws/aurora-dsql-node-postgres-connector`. Lambda runtime only provides `@aws-sdk/*`; other `@aws/*` packages must be bundled by esbuild.