learn-cdk-serverless

目的

簡単なTODO Webアプリケーションを AWS 上でサーバーレスに構築する。TypeScript を可能な限り使用する（CDK、Lambda、フロントエンド）。

概要

このリポジトリは、学習目的で作成するサーバーレス TODO アプリの設計と実装を行います。バックエンドは CDK(TypeScript) でインフラを定義し、Lambda(TypeScript) と DynamoDB を用いた CRUD API を提供します。フロントエンドは React + TypeScript で実装し、S3 + CloudFront で静的配信します。

高レベルアーキテクチャ

• Frontend: React (TypeScript) — S3 (静的ホスティング) + CloudFront
• API: API Gateway (HTTP API v2) -> Lambda (TypeScript)
• DB: DynamoDB (単一テーブル: Todos)
• IaC: AWS CDK (TypeScript)
• 認証: 当面は未実装（要件次第で Cognito を追加）

アーキテクチャ図（テキスト）:

Client (ブラウザ) └─ CloudFront -> S3 (静的ファイル) └─ API Gateway (HTTP API) └─ Lambda (TodoHandlers) └─ DynamoDB (Todos テーブル)

コンポーネント詳細

1. DynamoDB

   • テーブル名: TodosTable
   • パーティションキー (PK): id (string)
   • その他属性: title (string), completed (boolean), createdAt (ISO 8601 string)
   • 設計: 単純な CRUD 用。将来の検索要件が増えたらセカンダリインデックスを追加する。

2. Lambda

   • 言語: TypeScript
   • ビルド: esbuild などでバンドル
   • エントリ: src/lambda/todoHandler.ts
   • 標準的なエンドポイントを実装（下記 API 仕様参照）

3. API Gateway (HTTP API v2)

   • ルーティング:
     • GET /todos -> 全件取得
     • POST /todos -> 作成
     • GET /todos/{id} -> 単一取得
     • PUT /todos/{id} -> 更新
     • DELETE /todos/{id} -> 削除

4. Frontend

   • React + TypeScript
   • S3 にビルド成果物を配置し、CloudFront で配信
   • 簡単な UI: TODO の一覧、追加、編集、削除

データ契約（JSON 例）

新規作成リクエスト（POST /todos）:

{ "title": "買い物に行く" }

レスポンス / 保存される項目:

{ "id": "uuid-v4", "title": "買い物に行く", "completed": false, "createdAt": "2026-03-13T12:00:00Z" }

IAM 権限（最小権限の方針）

• Lambda が DynamoDB に対して必要とする権限: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan（要件に合わせて限定する）。
• CloudFront/S3 の権限はデプロイ用 IAM ユーザー/ロールに限定。

CDK 上では、Lambda に対して具体的なリソース ARN を指定し、最小限のポリシーを割り当てます。

CDK の構成（提案）

• stacks/
  • core-stack.ts (DynamoDB, Lambda, HTTP API の定義)
  • frontend-stack.ts (S3 バケット + CloudFront)

各 Lambda は TypeScript で実装し、esbuild でバンドルしてデプロイするワークフローを推奨します。

デプロイ手順（短い例）

以下は開発者向けの簡易手順例です（PowerShell を想定）。

# 1. 依存関係をインストール
npm install

# 2. CDK の初期化・ブートストラップ（初回のみ）
npx cdk bootstrap aws://<ACCOUNT_ID>/<REGION>

# 3. CDK を synth/diff/デプロイ
npx cdk synth
npx cdk diff
npx cdk deploy --all

フロントエンドは通常 npm run build（React）でビルドして S3 にアップロードするか、CDK の BucketDeployment を使ってパイプライン化します。

ローカル開発

• Lambda の単体ローカル実行: jest などでユニットテストを書く。必要なら aws-sam-cli の sam local invoke を使ってエンドツーエンドのローカル実行も可能。
• フロントエンド: npm start でローカル開発サーバーを起動し、API のエンドポイントは環境変数で差し替え。

品質ゲート（推奨）

• ビルド: npm run build（Lambda/Frontend）
• Lint/Typecheck: npm run lint, npm run typecheck
• テスト: 単体テスト (Jest)、簡易的な統合テスト

CI/CD を導入する場合は、GitHub Actions や CodeBuild を利用し、cdk synth → cdk deploy のパイプラインを作るのが良いです。

次のステップ（提案）

1. この README の設計方針で問題ないか確認してください。
2. 同意が得られれば、リポジトリに CDK の雛形 (TypeScript) と Lambda の最小実装を追加します。
3. その後、フロントエンドの scaffold（create-react-app / Vite + TypeScript）を追加します。

必要であれば認証（Cognito）や CI/CD、カスタムドメインの設計も追加します。

---

（設計: 2026-03-13）