基本設計書 - 社内ブログシステム

はじめに

本記事は、社内マイブログシステムの基本設計書をブログ記事として公開するものです。完全な設計書はリポジトリ内の docs/basic-design.md で管理しています（ソースは非公開で運用しているため、リポジトリ自体は外部非公開です）。

システム概要

目的

社内エンジニアが技術知識を蓄積・共有するための個人ブログプラットフォームを構築します。Cloudflare Pages上に静的サイトとしてデプロイし、AI駆動の記事自動生成・投稿機能を備えます。

スコープ

#	機能	説明
1	ブログサイト	Astro製の静的ブログ本体（記事表示・検索・コメント・RSS）
2	AI自動投稿	Claude Code CLIによる記事自動生成（Claude API / OpenAI APIフォールバック）
3	CI/CD	GitHub Actionsによる自動ビルドとCloudflare Pagesへの自動デプロイ
4	配布物管理	スクリプト・ツール・テンプレートのダウンロード機能

リポジトリとホスティング

• リポジトリ: GitHub（private）。ソースコードは非公開で運用する方針
• ホスティング: Cloudflare Pages（プロジェクト dawneel-blog）。リポジトリを非公開に保ったまま公開サイトを配信できる
• 公開URL: https://dawneel.lacue.uk/blog-modern/（ルート / は /blog-modern/ へリダイレクト）
• コメント: GiscusのバックエンドとなるGitHub Discussionsには、コメント専用の公開リポジトリを使用

技術スタック

カテゴリ	技術	バージョン	選定理由
SSG	Astro	5.x	ゼロJS出力、Content Collections、View Transitions
スタイル	Tailwind CSS	4.x	@themeブロック、Viteプラグイン統合
コンテンツ	MDX	-	コンポーネント埋め込み、Content Collections統合
検索	Pagefind	1.x	ビルド時インデックス、依存ゼロ、静的サイト最適
コメント	Giscus	-	GitHub Discussions連携、無料
分析	GoatCounter	-	プライバシー重視、API経由データ取得
ハイライト	Shiki	内蔵	ライト/ダークのデュアルテーマ対応
ホスティング	Cloudflare Pages	-	無料、グローバルCDN、非公開リポジトリのまま公開配信可能
デプロイCLI	Wrangler	4.x	GitHub Actionsから wrangler pages deploy を実行

システム構成図

graph TB
    subgraph "ユーザー環境"
        Browser["ブラウザ"]
        AdminPC["運営者PC<br/>(Claude Code / VS Code)"]
    end

    subgraph "GitHub"
        Repo["GitHubリポジトリ (private)"]
        Actions["GitHub Actions"]
        CommentsRepo["コメント用公開リポジトリ<br/>(GitHub Discussions)"]
    end

    Pages["Cloudflare Pages<br/>(プロジェクト: dawneel-blog)<br/>https://dawneel.lacue.uk"]

    subgraph "外部サービス"
        AIAPI["Claude Code CLI<br/>(フォールバック: Claude / OpenAI API)"]
        GoatCounter["GoatCounter<br/>(アクセス解析)"]
        GiscusApp["Giscus<br/>(コメント)"]
    end

    AdminPC -->|"git push"| Repo
    Repo -->|"push / workflow_dispatch"| Actions
    Actions -->|"wrangler pages deploy"| Pages
    Actions -->|"API Call (記事自動生成)"| AIAPI
    Actions -->|"git commit & push"| Repo

    Browser -->|"HTTPS"| Pages
    Browser -->|"閲覧数カウント"| GoatCounter
    Browser -->|"コメント読み書き"| GiscusApp
    GiscusApp -->|"Discussions API"| CommentsRepo

デプロイの流れは「push → GitHub Actionsでビルド・検索インデックス生成 → wrangler pages deploy でCloudflare Pagesへ配信」という一方向のパイプラインです。詳細はCI/CD設計書（別記事）を参照してください。

機能一覧

機能	概要
記事表示	一覧（グリッド）、詳細（目次・読了時間・関連記事）、年月別アーカイブ
タグ・カテゴリ	複数タグ + 単一カテゴリ。タグ別一覧・タグクラウド
全文検索	Pagefindによる静的全文検索。Ctrl+K ショートカット対応
ダークモード	手動切替 + prefers-color-scheme 連動。localStorageで永続化
コメント	Giscus（GitHub Discussions）
RSS / サイトマップ	@astrojs/rss / @astrojs/sitemap によるビルド時生成
アクセス解析	GoatCounter（Cookie不使用）
AI自動投稿	毎月1日・15日にAI APIで記事を自動生成・公開（aiGenerated: true バッジ表示）
配布物管理	ダウンロードカードによるスクリプト・テンプレート配布

コンテンツ管理（Content Collections）

記事はMarkdown / MDXファイルとして src/content/blog/ に格納し、Astro Content CollectionsとZodスキーマで型安全に管理します。

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    heroImage: z.string().optional(),
    tags: z.array(z.string()).default([]),
    category: z.string().default("general"),
    draft: z.boolean().default(false),
    aiGenerated: z.boolean().default(false),
  }),
});

• draft: true の記事はビルド対象から除外され、公開サイトには一切出力されません
• aiGenerated: true の記事には「AI Generated」バッジを表示し、AI生成記事であることを明示します
• フロントマターがスキーマに合わない場合はビルドエラーとなり、CIで品質を担保します

非機能・セキュリティ

非機能要件

項目	目標値
Lighthouse Performance	95+
Lighthouse Accessibility	95+
Lighthouse SEO	100
LCP	< 2.5s
CLS	< 0.1
可用性	CloudflareグローバルCDNによる静的配信

セキュリティ設計

• サーバーサイドコードが存在しないため、SQLi / RCE / セッションハイジャックの脅威を構造的に排除
• AI APIキー・Cloudflare APIトークンはGitHub Secretsで管理し、クライアントに露出しない
• GitHub Actionsの権限は最小権限設計（デプロイ: contents: read / AI投稿: contents: write + actions: write）
• Cloudflare APIトークンはPages編集権限のみに限定
• 外部スクリプト（GoatCounter, Giscus）は信頼されたドメインからのみ読み込み
• Pagefindの検索インデックスはビルド時生成のためXSSリスクなし
• 本体リポジトリはprivateとし、ソースコードや運用設定を外部に公開しない。サイト本体はCloudflare Pagesが配信するため、リポジトリの可視性は公開サイトに影響しない

外部サービス

サービス	役割	備考
Cloudflare Pages	ホスティング	無料・グローバルCDN・独自ドメイン配信
GitHub Actions	CI/CD・AI自動投稿	リポジトリ一体型ワークフロー
Giscus	コメント	コメント専用の公開リポジトリのDiscussionsをバックエンドに使用
GoatCounter	アクセス解析	プライバシー重視・Cookie不使用
Claude Code / AI API	記事自動生成	Claude Code CLI（サブスクリプション認証）が主、Claude API / OpenAI APIはフォールバック

まとめ

本設計は「静的サイト + AI駆動運用 + 無料サービスの組み合わせ」により、運用コストゼロで高品質なブログプラットフォームを実現します。本記事はダイジェスト版で、完全版の設計書はダウンロードページからMarkdownファイルとして入手できます。