ai-blog アーキテクチャ

概要

• フレームワーク: Next.js 16 (App Router, Turbopack) + React 19 + TypeScript
• AIモデル: gemini-2.5-flash（Google Search Grounding）+ imagen-4.0-generate-001
• 永続化: S3（Primary）/ Local FS（Fallback、S3_BUCKET 未設定時）
• 実行基盤: AWS Amplify Hosting（Static + SSR、Lambda@Edge は不使用）
• 定期実行: GitHub Actions（5 ワークフロー）

システム構成（Context）

flowchart LR
  Reader[読者] --> App[Next.js App on Amplify]
  Admin[管理者] --> App
  App -- workflow_dispatch --> GHA[GitHub Actions]
  GHA -- 直接実行 --> Gen[Gemini / Imagen]
  Gen --> S3[(S3: posts / images / index)]
  App --> S3
  Search[検索エンジン] --> App
  Reader -- SNSシェア --> SNS[X / Facebook / LINE]

コンテナ構成（Container）

flowchart TB
  Browser[Browser]
  subgraph Amplify
    UI[UI Layer\nsrc/app, src/components]
    API[API Layer\nsrc/app/api/*]
    Lib[Domain/Infra\nsrc/lib/posts.ts, src/lib/s3.ts]
  end
  subgraph GitHubActions
    Scripts[scripts/*.mjs]
  end
  S3[(S3 Bucket)]
  Local[(Local FS\ncontent/posts, public/generated-images)]
  Gemini[gemini-2.5-flash\n+ googleSearch]
  Imagen[imagen-4.0-generate-001]

  Browser --> UI
  UI --> Lib
  API --> Lib
  API -- workflow_dispatch --> Scripts
  Scripts --> Gemini
  Scripts --> Imagen
  Scripts --> S3
  Lib --> S3
  Lib -.fallback.-> Local

主要フロー

1) 記事閲覧

1. / および /posts/[slug] で getAllPosts / getPostBySlug を実行
2. src/lib/posts.ts が S3 優先、なければ /tmp → バンドルの順でフォールバック
3. Markdown → HTML 変換（remark + remarkGfm）後、後処理：
   • 未置換 {{IMAGE_N}} マーカーを除去
   • <img> に loading="lazy" decoding="async" を付与
   • ## 参考文献 直後の <ol> を / 区切りの <p class="references-compact"> に変換
   • 見出し（h2/h3）に id を付与（目次・アンカーリンク用）
4. ISR で配信（revalidate = 60）

2) 管理画面から記事生成（推奨パス）

1. ブラウザ → /admin → /api/auth で Bearer token 発行
2. /api/generate が GitHub の workflow_dispatch を呼ぶだけ（直接生成しない）
3. GitHub Actions 上で scripts/scheduled-generate.mjs が走る
4. 完了後 ISR キャッシュが切れたら公開面に反映
5. CloudFront / Lambda 29 秒タイムアウト回避のためにこの構成を取る

2′) 旧フロー（/api/generate-article）

• 直接 Gemini を呼んで生成。maxDuration = 300 を設定済みだが、CloudFront 29 秒制限に当たる可能性があるため現在は非推奨

3) 定期バッチ生成（GitHub Actions cron）

4) 参考文献（Grounding URL）取得フロー

Gemini が JSON 出力モードで googleSearch を発火させない / 架空 URL を吐く問題への対策

1. プライマリ呼び出し（gemini-2.5-flash で本文 JSON を生成、grounding tool 付き）
2. 必ずフォールバック検索を gemini-2.5-flash で再実行（grounding 安定取得用）
3. mergeSourceUrls(primary, fallback) で URI ベース重複排除してマージ
4. URL がある段落の末尾に 出典: [name](url) — <url> をラウンドロビンで挿入
5. 末尾に ## 参考文献 を番号付きリストで追加（フロント側で / 区切りに整形）
6. groundingChunks 由来の URL のみ採用（Gemini が JSON 内に書いた URL は 404 になることがあるので使用禁止）

モデル利用箇所

• 本文生成 + Grounding: gemini-2.5-flash
  • scripts/scheduled-generate.mjs
  • scripts/category-generate.mjs
  • scripts/generate-multiple.mjs
  • scripts/_shared.mjs（共通ユーティリティ）
  • src/app/api/generate-article/route.ts（旧フロー）
• 画像生成: imagen-4.0-generate-001（同上）

永続化レイアウト

S3

{S3_BUCKET}/
├── posts/{slug}.md
├── images/{slug}-cover.webp
├── images/{slug}-image_1.webp ... image_N.webp
└── posts-index.json          # 最新 30 件のメタ（重複テーマ回避用）

Local（フォールバック / 開発時）

content/posts/{slug}.md
public/generated-images/{slug}-cover.webp
                       /{slug}-image_N.webp

src/lib/s3.ts::isS3Enabled() が S3_BUCKET の有無で切り替える。

API レイヤ（src/app/api/）

UI コンポーネント（src/components/）

Markdown frontmatter

---
title: "..."
date: "2026-04-29"                         # JST（一覧表示用）
datetime: "2026-04-29T09:00:00+09:00"      # JST（ソート用）
summary: "..."
tags: ["AI", "LLM"]
source: "AI Auto-Generated"
coverImage: "/api/images/images/{slug}-cover.webp"  # 画像生成成功時のみ
---

本文中の {{IMAGE_1}} などのマーカーが画像生成完了後に ![alt](url) に置換される。失敗マーカーは posts.ts::parseMarkdown() の正規表現で除去（安全策）。

SEO / 構造化データ

• src/app/sitemap.ts / robots.ts を自動生成
• /posts/[slug] で BreadcrumbList + BlogPosting JSON-LD を出力
• OGP / Twitter Card は generateMetadata() で記事ごとに動的生成
• /feed.xml を提供

セキュリティと運用

• 管理 API は Authorization: Bearer ... 必須（verifyAuth() で検証）
• /api/auth に IP 単位のログイン試行制限
• 画像は /api/images/[...path] プロキシ経由で配信（S3 Block Public Access を維持、IAM 認証で取得）
• amplify.yml の preBuild フェーズで .env.production を毎回新規生成（>> 追記による重複を回避）

環境変数