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

Astro + GitHub Pagesで構築した社内マイブログシステムの基本設計書。システム構成、技術スタック選定理由、機能仕様、データ設計、セキュリティ設計を網羅します。

6min read 設計書 手動投稿
#設計書 #Astro #GitHub Pages #アーキテクチャ
no. 006

はじめに

本記事は、社内マイブログシステムの基本設計書をブログ記事として公開するものです。完全な設計書は docs/basic-design.md で管理しています。

システム概要

目的

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

スコープ

#機能説明
1Blog Modernテック系モダンデザインのブログサイト
2Blog Magazineマガジン/ポートフォリオ風デザインのブログサイト
3AI自動投稿Claude API / OpenAI APIによる記事自動生成
4CI/CDGitHub Actionsによる自動ビルド・デプロイ
5配布物管理スクリプト・ツール・テンプレートのダウンロード機能

システム構成

アーキテクチャ概要

┌─────────────────────────────────────────────┐
│               ユーザー環境                    │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │ ブラウザ  │  │Claude Code│  │ GitHub UI │  │
│  └────┬─────┘  └────┬─────┘  └─────┬─────┘  │
└───────┼──────────────┼──────────────┼────────┘
        │              │              │
┌───────┼──────────────┼──────────────┼────────┐
│       ▼     GitHub Platform         ▼        │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │  GitHub   │  │  GitHub   │  │ GitHub    │  │
│  │  Pages    │  │  Actions  │  │ Repo      │  │
│  └──────────┘  └──────────┘  └───────────┘  │
└──────────────────────────────────────────────┘
        │              │
┌───────┼──────────────┼───────────────────────┐
│       ▼     外部サービス                      │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │GoatCounter│  │  Giscus  │  │ Claude/   │  │
│  │(閲覧数)   │  │(コメント) │  │ OpenAI API│  │
│  └──────────┘  └──────────┘  └───────────┘  │
└──────────────────────────────────────────────┘

技術スタック

カテゴリ技術バージョン選定理由
SSGAstro5.xゼロJS出力、Content Collections、View Transitions
スタイルTailwind CSS4.x@themeブロック、Viteプラグイン統合
コンテンツMDX-コンポーネント埋め込み、Content Collections統合
検索Pagefind1.xビルド時インデックス、依存ゼロ、静的サイト最適
コメントGiscus-GitHub Discussions連携、無料
分析GoatCounter-プライバシー重視、API経由データ取得
ハイライトShiki内蔵デュアルテーマ対応
デプロイGitHub Pages-無料、GitHub Actions連携

機能仕様

記事管理

Content Collectionsにより型安全なフロントマター管理を実現：

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

検索機能

Pagefindによるビルド時インデックス生成で、フロントエンドのみで全文検索を実現します。Ctrl+K ショートカットにも対応。

ダークモード

CSS prefers-color-scheme とlocalStorageの組み合わせで、ユーザー選択を永続化。View Transitions時にも状態を維持します。

AI自動投稿

  • スケジュール投稿: GitHub Actions cron（毎月1日・15日）
  • 手動投稿: Claude Codeの /blog-post スキルで即時生成
  • プロバイダー: Claude API（主）/ OpenAI API（フォールバック）

データ設計

ディレクトリ構成

blog-modern/
├── src/
│   ├── content/
│   │   ├── blog/          # ブログ記事 (*.md, *.mdx)
│   │   └── downloads/     # 配布物定義 (*.md)
│   ├── components/        # UIコンポーネント
│   ├── layouts/           # ページレイアウト
│   ├── pages/             # ルーティング
│   ├── styles/            # グローバルCSS
│   └── utils/             # ユーティリティ関数
├── public/                # 静的アセット
└── astro.config.mjs       # Astro設定

セキュリティ設計

静的サイトの構造的メリット

  • サーバーサイドコードが存在しないため、SQLi / RCE / セッションハイジャックの脅威を構造的に排除
  • APIキーはGitHub Secretsで管理、クライアントに露出しない
  • GitHub Actionsの権限は contents: write のみの最小権限設計

クライアントサイドセキュリティ

  • 外部スクリプト（GoatCounter, Giscus）は信頼されたドメインからのみ読み込み
  • Pagefindはビルド時生成のためXSSリスクなし

非機能要件

項目目標値
Lighthouse Performance95+
Lighthouse Accessibility95+
Lighthouse SEO100
LCP< 2.5s
FID< 100ms
CLS< 0.1
可用性99.9%（GitHub Pages SLA準拠）

まとめ

本設計は「静的サイト + AI駆動運用 + 無料サービス組み合わせ」により、運用コストゼロで高品質なブログプラットフォームを実現します。詳細は完全版の設計書を参照してください。

Share

関連展示 Related

芳名帳 Comments