( 姉妹本:源内AIアプリのソースコードを理解してみよう のご紹介はこちら )
デジタル庁のOSS「源内Web」のソースコードを読む本を書きました
はじめに
先日、「源内Webアプリのソースコードを理解してみよう」 という本を書きました。
デジタル庁が公開しているOSS「genai-web」のソースコードを題材にした技術書です。この記事では、なぜこの本を書いたのか、どんな内容なのかをお伝えします。
きっかけ：「読み方」を教えてくれる本がなかった
genai-webは、行政職員向けに生成AIを安全・迅速に提供するための基盤として、デジタル庁が開発・公開しているOSSです。React 19、AWS CDK、TypeScript、Cognito、DynamoDB、SQS……モダンな技術スタックが惜しみなく使われており、実務のベストプラクティスが詰まったコードベースです。
ただ、正直に言うと、このリポジトリ、最初は読み方がわかりませんでした。
コードの量が多い。設計の意図がREADMEだけではわからない。packages/cdk/にはインフラ定義とLambdaハンドラーが共存している。DynamoDBのテーブルがなぜ4つに分かれているのか？ API Gatewayがなぜ2つあるのか？
GitHubを眺めているだけでは、「なぜそうなっているのか」がなかなか見えてこないんです。
こういう「読めるけど理解できない」状態を抜け出すための地図として、この本を書きました。
本書のアプローチ
本書は、コードの全行を解説することを目指していません。
代わりに、「なぜこの設計になっているのか」 を軸にしています。
たとえば：
- DynamoDBのテーブルが4つに分かれているのは、アクセスパターンと権限境界の設計が絡んでいるから
- API Gatewayが2つあるのは、通常のAPIとチームアクセス制御APIで責務を分けているから
- IAMポリシーとLambdaコードの両方で権限チェックをしているのは、「二重防衛」という意図的な設計だから
こういった「なぜ」を理解すると、コードが急に読めるようになります。知らない街の地図を手に入れたような感覚です。
章構成
全9章・188ページです。
第1章：プロジェクト概要と設計思想
源内WebはAWSのOSS「GenU」を出発点にしていますが、独立して進化した別プロダクトです。チーム管理・外部AIアプリ（ExApp）連携・デジタル庁デザインシステム適用・アクセシビリティ対応という4方向で大幅に拡張されています。この章でその全体像をつかみます。
第2章：アーキテクチャ全体像
CDKのエントリポイントからスタック構成全体を読み解きます。CloudFront、Cognito、API Gateway、DynamoDB、Lambda……各サービスがどのように連携しているかを、コンストラクトの依存関係から理解します。
第3章：環境構築とデプロイ
ただの手順書ではありません。パラメータファイルの仕組みやsetup-env.shの設計思想、GitHub ActionsでのOIDC認証（AWSシークレットをGitHubに持たない）の実装まで踏み込みます。
第4章：認証とアクセス制御
Cognitoトリガー（PreSignUp / PostConfirmation / CustomEmailSender）の実装、3層のロールモデル、IAMポリシーとLambdaコードによる二重防衛。「なぜこんなに念入りに権限チェックするのか」が腑に落ちる章です。
第5章：フロントエンド実装
SWRとZustandをどう使い分けているか、LambdaのストリーミングAI呼び出しの仕組み、そしてJIS X 8341-3:2016 AA準拠のアクセシビリティ対応がコードレベルでどう実現されているかを解説します。
第6章：AIアプリ（ExApp）の仕組み
源内Webの最も特徴的な機能です。JSON定義からフォームを自動生成し、外部AIサービスにリクエストを送り、SQSで非同期実行をポーリングする仕組みを一気通貫で追います。
第7章：チーム管理機能の実装
DynamoDBのシングルテーブル設計、ZodスキーマによるバリデーションとDynamoDB+Cognitoの同時更新、TransactWriteを使った整合性保証……実務でも使えるパターンが多く登場します。
第8章：テストとコード品質
Vitest・aws-sdk-client-mock・cdk-nagによるテスト戦略と、BiomeによるLint/フォーマット管理。テストの書き方だけでなく、「何をテストすべきか」の考え方を示します。
第9章：CI/CDとセキュリティ設計
CloudFront WAF・セキュリティヘッダー・KMS・cdk-nagによる多層防衛、Bedrock GuardrailによるPII検出、CloudWatchアラームとSlack通知。セキュリティ要件の高い実務プロジェクトの設計が参考になる章です。
こんな方に読んでほしい
本書が想定している読者はこういう方です。
- AWSとTypeScriptの基礎知識はある
- 大規模な実務用リポジトリを読む機会が増えてきた
- コードは追えるが、設計の意図が読み取れないことがある
- 生成AI基盤の実装に興味がある
「コードを書けること」と「コードを読めること」は別の能力です。本書はその「読む力」を、具体的なコードベースを通じて養うことを目指しています。
対象バージョンについて
本書は2026年5月時点のgenai-web v1.0.5（コミットf20366a）を対象にしています。OSSは継続的に更新されるため、最新コードとは差異が出る場合があります。実際の開発ではGitHubリポジトリを合わせて参照してください。
おわりに
「コードは読めるのに、なんでこう書いてあるのかわからない」——そういう壁は、ちゃんと乗り越えられます。
誰かのコードを読む力は、自分のコードを書く力に直結します。genai-webというリアルな実務プロダクトを題材にしながら、その力を一緒に育てていきたいと思って書きました。
ご興味があれば、ぜひ手に取ってみてください。