ブログサイト構築 — 全体アーキテクチャ

このシリーズについて

本ブログ（octomblog）の構築で採用した技術・設計の記録。 なぜその選択をしたかに焦点を当て、同種のサイトを構築する際の参考にできるようまとめる。

全体構成

ブラウザ
  │
  ├─ 静的ページ（HTML/JS/CSS）── Cloudflare Pages CDN（全世界エッジ配信）
  │   └─ ビルド時に全コンテンツを静的生成（getStaticPaths / prerender）
  │       ├─ Markdown → HTML 変換（Astro Content Collections）
  │       └─ OGP 画像生成（Satori + @resvg/resvg-js）→ dist/ogp/**/*.png
  │
  └─ 動的API（/api/views/...）── Cloudflare Pages Functions
      └─ Cloudflare KV に閲覧数を read/write

技術スタック

層	技術	役割
フレームワーク	Astro v6	SSG ビルド・コンポーネント管理
コンテンツ管理	Markdown + frontmatter	記事・Docs の管理
OGP画像生成	Satori + @resvg/resvg-js	タイトル入り PNG をビルド時生成
スタイリング	Tailwind CSS v4	ユーティリティファースト CSS
検索	Pagefind	ビルド後に全文インデックスを生成
ホスティング	Cloudflare Pages	CDN + Functions の統合プラットフォーム
動的API	Cloudflare Pages Functions	閲覧数カウント
永続化	Cloudflare KV	閲覧数の保存

設計の基本方針

「ビルド時にできることはビルド時に」

ランタイムのコンピューティングコストをゼロに近づけるため、できる限りビルド時に処理する。

• Markdown → HTML: ビルド時変換（SSG）
• OGP 画像: ビルド時 PNG 生成（Satori）
• 検索インデックス: ビルド後 Pagefind 生成
• サイトマップ: ビルド時 sitemap.xml 生成

閲覧数カウントだけは書き込み操作を要するため Cloudflare KV + Pages Functions で動的処理。

Functional Core, Imperative Shell

Astro コンポーネントは「データ取得（I/O）」「変換ロジック」「描画」が混在しやすい。 src/lib/ に純粋関数を切り出し、ページは I/O の調停役に徹する設計にした。

src/lib/          ← 純粋関数（副作用ゼロ・テスト容易）
src/pages/        ← I/O 調停（getCollection + lib + コンポーネント）
src/components/   ← 描画層（props → HTML）

シリーズ構成

#	タイトル	内容
1	全体アーキテクチャ（本ドキュメント）	スタック選定・設計方針
2	SSG と MPA の設計	Astro の静的生成と部分的クライアント処理
3	Cloudflare ホスティング	Pages・Functions・KV の連携
4	OGP 画像の自動生成	Satori + resvg のビルド時生成
5	Cloudflare D1 入門	リレーショナルDBをエッジで使う選択肢