Source Library

---

🎬 Source Libraryを体験する

---

🎯 Source Libraryについて

Source Libraryは、初期刊本や一次資料を読みやすく、引用可能な形で提供することを目的としたオープンなデジタルライブラリです。錬金術、ヘルメス文書、カバラ、薔薇十字主義、近世科学を専門とし、歴史学研究と現代的な探究をつなぐ文献を扱っています。

🌟 Source Libraryが選ばれる理由

• ✨ 原典を第一に — 原語のテキストと、AI で強化された翻訳を並べて読めます
• 🎓 引用可能な学術資料 — すべての書籍に DOI と学術メタデータが付与されます（USTC との連携、版の追跡）
• 🏛️ パートナーのサブドメイン — Bibliotheca Philosophica Hermeticaなどの機関が、独自ドメインで読書室を運営できます
• 🔍 発見 — コレクション、図版ギャラリー、セマンティック検索を通じて、見過ごされてきた文献を見つけられます
• ✅ 厳格な品質保証 — 公開前に、手作業による検証、画像品質の評価、OCR の検証を行います

このプラットフォームでは、Internet Archive、Gallica、Bodleian、Wellcomeなどのデジタル文化遺産パートナーから、毎月約15,000ページを取り込んでいます。

---

🚀 クイックスタート

💻 開発環境

# 🍴 Clone and install
git clone https://github.com/Embassy-of-the-Free-Mind/sourcelibrary-v2.git
cd sourcelibrary-v2
npm install

# ⚙️ Configure environment (see .env.example for required variables)
# Must include: MongoDB Atlas connection, Google Gemini API key, Vercel Blob token

# ▶️ Start dev server
npm run dev

http://localhost:3000を開きます

---

📋 技術スタック

🎨 フロントエンド	Next.js 16, React 19, TailwindCSS, Lucide icons
⚙️ バックエンド	Next.js API routes, 非同期処理用のAWS Lambda
💾 データベース	MongoDB Atlas（プライマリ）、Supabase（埋め込み）
🤖 AI/ML	Google Gemini 3.1（OCR、翻訳、要約）
🗂️ ストレージ	Vercel Blob（画像）、AWS S3（アーカイブ）、Cloudflare R2（アーカイブ）
🔐 認証	MongoDBアダプターを使用したNextAuth v5
🚀 DevOps	Vercel（ホスティング）、GitHub（VCS）、Playwright（E2Eテスト）
✔️ テスト	Vitest（ユニット／統合）、Playwright（E2E）
🔎 検索	PostgreSQL FTS + Supabaseによるセマンティック検索

📦 主な依存関係：

• sharp — 画像のサイズ変更とトリミング
• @google/generative-ai — Gemini APIとの連携
• xml2js — USTCメタデータの解析
• @modelcontextprotocol/sdk — エージェント連携用のMCPサーバー
• stripe — 寄付とサブスクリプションの処理

---

📚 主な機能

📖 閲覧とナビゲーション

• ⚡ ページのページネーション — 100 ページ以上を瞬時に移動できます
• 🔍 全文検索 — OCR テキストと翻訳を横断して検索できます
• 📌 引用の生成 — DOI リンク付きで文章をコピーして引用できます

🔄 処理パイプライン

• 🧩 スマートな見開き検出 — 2 ページ見開きの中央部分を自動検出します（Gemini AI または ML ベース）
• ✍️ 高精度 OCR — 言語固有のモデル（ラテン語、ドイツ語、ギリシャ語、アラビア語など）を使用する Gemini Vision API
• 🗣️ 文脈を考慮した翻訳 — 学術的な正確さを保つため、ページ間の一貫性を維持します
• 🖼️ ギャラリー抽出 — AI を活用して図版を検出し、カタログ化します

🎨 キュレーションと発見

• 📑 テーマ別コレクション — 編集者が選定したコレクション（例：「錬金術と変成」、「カバラと神秘主義」）
• 🏛️ ギャラリー閲覧 — すべての書籍から選定された画像（美術館品質のメタデータ）
• 📚 関連版 — 翻訳版、復刻版、派生作品を相互にリンクします
• 🔗 権威データベースとの連携 — USTC、VIAF などの学術データベースに接続します

📤 学術向けエクスポート

• 📱 EPUB 生成 — 複数形式の電子書籍をエクスポートできます
• 📄 注釈付き PDF — レイアウトを保持し、学術的な注釈を追加します
• 🆔 DOI の登録 — Zenodo との連携により書籍のバージョンを管理し、長期的な引用を可能にします

🏢 テナントのサブドメイン

• 🏛️ 独立した閲覧室 — パートナーはカスタムドメイン（例：bph.sourcelibrary.org）で選定したサブセットをホストできます
• 🎨 ブランディングとナビゲーション — テナントごとに UI を全面的にカスタマイズできます
• 🔒 アクセス制御 — コレクションを一般公開または会員限定に設定できます

---

🏗️ アーキテクチャの概要

📊 データモデル

📚 書籍には構造化されたメタデータが含まれます：

• 🏛️ 書誌情報 — タイトル、著者、言語、出版日、USTC ID
• 🖼️ 画像 — ソース（Internet Archive、Gallica など）へのリンク、アーカイブ状況
• ⚙️ 処理情報 — OCR の状況、翻訳言語、抽出メタデータ
• 🎨 キュレーション情報 — コレクション、階層（注目／標準）、公開設定

📄 ページには個々のページデータが保存されます：

• 📸 元画像 — ソース写真または PDF ページ
• ✂️ 分割座標 — 2 ページ見開き用の切り抜き境界（0-1000 のスケール）
• ✍️ OCR 出力 — Gemini による抽出結果の生データ＋言語メタデータ
• 🗣️ 翻訳 — 学術的な注釈付きの英語翻訳
• 🖼️ 図版 — 品質スコアと説明を含む検出済み画像

🖼️ ギャラリー画像は抽出された図版です：

• 🏷️ メタデータ — 主題、人物、シンボル、様式、技法、時代
• ⭐ 品質スコア — 0〜1.0 の評価（0.5 未満は除外）
• 🔗 来歴 — 元の書籍とページ、およびその書籍へのリンク

🎨 画像の階層システム

すべてのページ画像は、リクエストに応じて /api/image 経由でリサイズされます：

階層	寸法	品質	📱 用途
サムネイル	幅 400px	70% JPEG	グリッド、ナビゲーション、ソーシャル共有
表示用	幅 1200px	80% JPEG	メインの閲覧画面、注釈に適したサイズ
フル	幅 2400px	90% JPEG	拡大鏡、全画面表示、印刷

分割ページは座標を使って非破壊的に切り抜かれます。元画像は常に保持されます。

🔄 処理パイプライン

📥 Import → ✂️ Split Detection → ✍️ OCR → 🗣️ Translation → 🎨 Enrichment → 🌍 Publishing

1. 📥 インポート — 画像をアップロードするか、IIIF 経由で IA／Gallica からインポートするか、URL を貼り付けます
2. ✂️ 見開き検出 — 2 ページ見開きを検出し、切り抜き境界を設定します
3. ✍️ OCR — Gemini Vision がページの言語に応じてテキストを抽出します
4. 🗣️ 翻訳 — Gemini が前のページの文脈を引き継ぎ、一貫性を保ちながら英語に翻訳します
5. 🎨 拡充 — 図版を抽出し、要約を生成して、コレクションを割り当てます
6. 🌍 公開 — visible: true を設定し、DOI を登録して、検索インデックスに追加します

バッチエンドポイントは Gemini Batch API を使用して、リクエストごとに最大 5 ページを処理します（50% 割安です）。

🔌 API ルート（主要）

ベース URL： https://sourcelibrary.org（本番環境）または http://localhost:3000（.env.local を設定したローカル開発環境）。

よくある 404 の原因： /api/bph/books や /api/bph/books/[id] のようなパスは存在しません。BPH カタログ API は /api/embed/bph/... 配下にあります。また、トップレベルの /api/[tenant]/books ルートもありません。テナントの書籍一覧には、/api/books/library または以下の埋め込みルートを使用します。

公開読み取り API（現時点で認証不要）

エンドポイント	メソッド	目的
/api/search?q=<query>	GET	書籍とページ翻訳を対象とした全文検索
/api/books?limit=100&offset=0	GET	シンプルな書籍一覧（全体カタログ。visible: true で、インデックス登録済みのもののみ）
/api/books/library?limit=100&skip=0	GET	詳細な閲覧 API — 検索、並べ替え、フィルター、コレクション
/api/books/[id]	GET	書籍のメタデータ（Mongo の id または slug を受け付けます）
/api/books/[id]/quote?page=<n>	GET	引用可能な文章と書式付き引用（本文内、脚注、BibTeX、DOI）
/api/gallery?limit=24	GET	イラスト／アートワークの検索
/api/image?url=<encoded-url>&w=400	GET	オンデマンドの画像リサイズと切り抜き
/api/embed/bph/books?limit=24	GET	BPH カタログ（ページネーション対応、検索可能）
/api/embed/bph/books/[slug]	GET	BPH 書籍の詳細
/api/embed/bph/featured	GET	おすすめの BPH 書籍
/api/embed/bph/collections	GET	BPH コレクション一覧
/api/embed/bph/languages	GET	BPH の言語ファセット
/api/embed/bph/suggest?q=alch	GET	BPH 検索のオートコンプリート
/api/embed/bph/stats	GET	BPH カタログの統計情報

テナント別の一覧（/api/bph/... ではありません）

パートナーのテナント（例：BPH）で絞り込むには、次のいずれかの方法を使用します。

方法	例
埋め込みプレフィックス（BPH に推奨）	GET /api/embed/bph/books?limit=24
Library API + クエリパラメーター	GET /api/books/library?tenant_slug=bph&limit=24
Host ヘッダー（サブドメイン）	https://bph.sourcelibrary.org/api/books/library?limit=24 を呼び出します — プロキシがテナントコンテキストを注入します
手動ヘッダー（上級者向け）	curl -H "x-tenant-slug: bph" https://sourcelibrary.org/api/books/library?limit=24

コードベースに存在する /api/[tenant]/books/[id]/... パスは、編集／処理用のルート（OCR の一括処理、インデックスの再構築など）であり、公開カタログの一覧ではありません。

認証が必要な API／内部 API

これらの API には、サインイン済みのセッション Cookie、編集者ロール、または（一部のデータセット用エンドポイントでは）Bearer API キーが必要です。認証なしで呼び出すと、401 または 403 が返されます。

エンドポイント	メソッド	目的
/api/books	POST	新しい書籍を作成します（編集者）
/api/books/[id]	PATCH	書籍のメタデータを更新します（キュレーター以上）
/api/books/[id]/batch-ocr-async	POST	OCR 一括処理ジョブをキューに登録します
/api/books/[id]/batch-translate-async	POST	翻訳一括処理ジョブをキューに登録します
/api/pages/[id]	PATCH	ページの OCR／翻訳を更新します
/api/jobs/[id]/process	POST	非同期ジョブプロセッサー（Lambda）

API の詳細な解説：docs/blog-source-library-api.md。MCP ツール（検索、引用、読み取り）：mcp-server/README.md。

🧪 API を試す（curl、Postman、ブラウザー）

以下の例はすべて本番環境に接続し、API キーは不要です。ローカルで実行する場合は、ベース URL を http://localhost:3000 に置き換えてください（MongoDB と環境変数が必要です）。

curl

# Search translated text
curl -s "https://sourcelibrary.org/api/search?q=quintessence&limit=5" | jq .

# List books (global catalogue)
curl -s "https://sourcelibrary.org/api/books?limit=5" | jq .

# Browse with filters and sort
curl -s "https://sourcelibrary.org/api/books/library?limit=5&sort=recent-translation&has_translation=true" | jq .

# BPH catalogue — note /api/embed/bph/, NOT /api/bph/
curl -s "https://sourcelibrary.org/api/embed/bph/books?limit=5&translated=true" | jq .

# BPH via tenant_slug on the library endpoint
curl -s "https://sourcelibrary.org/api/books/library?tenant_slug=bph&limit=5" | jq .

# Book metadata (id or slug)
curl -s "https://sourcelibrary.org/api/books/know-thyself-reger-von-ehrenhart" | jq .

# Citable quote for a page
curl -s "https://sourcelibrary.org/api/books/6836f8ee811c8ab472a49e36/quote?page=57" | jq .

# Gallery search
curl -s "https://sourcelibrary.org/api/gallery?subject=alchemy&limit=5" | jq .

jq による整形表示は任意です。生の JSON を見るには | jq . を省略してください。

Postman

1. 新しい GET リクエストを作成します。
2. URL に、たとえば https://sourcelibrary.org/api/embed/bph/books を設定します。
3. Params タブでクエリーキーを追加します：limit = 24、sort = title、translated = true
4. 上記の公開エンドポイントでは、Auth は No Auth のままにします。
5. 送信すると、JSON 本文とともに 200 が返されます。

ブラウザー

公開されている GET エンドポイントは直接開けます：

• 検索：quintessence
• BPH の書籍
• ライブラリ全体を閲覧

📁 ディレクトリ構造

src/
├── app/                         # 🎨 Next.js App Router
│   ├── book/[id]/               # 📖 Book detail, reading, processing
│   │   ├── page.tsx             # Main book hub
│   │   ├── split/page.tsx       # Split detection workflow
│   │   └── page/[pageId]/page.tsx      # Individual page view
│   ├── api/                     # 🔌 All API routes
│   │   ├── books/               # Book CRUD & batch ops
│   │   ├── pages/               # Page processing
│   │   ├── image/               # Image proxy & cropping
│   │   ├── jobs/                # Async job tracking
│   │   └── search/              # Full-text & semantic
│   ├── [tenant]/                # 🏢 Tenant subdomain routes
│   ├── gallery/                 # 🖼️ Illustration browsing
│   ├── collections/             # 📑 Collection pages
│   └── admin/                   # ⚙️ Admin dashboard
├── hooks/                       # 🎣 Reusable React hooks
└── lib/                         # 🛠️ Business logic & utilities
    ├── mongodb.ts               # Database operations
    ├── image-extraction.ts      # Illustration detection
    └── auth-helpers.ts          # Authentication utilities

scripts/
├── workers/                     # ⚙️ Lambda worker functions
│   ├── pipeline-orchestrator.mjs # Main processing pipeline
│   ├── image-extract-worker.mjs # Gallery extraction
│   └── ...
├── maintenance/                 # 🔧 One-off maintenance scripts
├── migrations/                  # 📊 Database schema updates
└── audit-bph-leaks.mjs          # 🔒 Tenant security verification

tests/
├── unit/                        # ✔️ Vitest unit tests
└── integration/                 # 🔗 Integration tests

prompts/                        # 🤖 AI system prompts
├── ocr/
├── translation/
├── split-detection/
└── ...

.claude/                        # 🧠 AI agent context
├── docs/                       # 📚 Detailed architecture docs
├── skills/                     # 🎯 Specialized agent skills
└── handoffs/                   # 📋 Incident reports & lessons

---

🔄 一般的なワークフロー

📥 Internet Archive から書籍をインポートする

// From the UI or via API
POST /api/books
{
  "ia_id": "thehermetic00fludd",
  "title": "The Hermetic and Alchemical Writings",
  "author": "Arthur Edward Waite",
  "language": "en",
  "ustc_id": "123456"
}

システムは次の処理を行います：

1. 📥 IA IIIF からページ画像を取得します
2. ✂️ 分割を検出し、切り抜き座標を生成します
3. 📤 OCR と翻訳のキューに追加します
4. 🌍 処理完了後に公開します

✂️ 分割された書籍を処理する

1. 🖥️ /book/[id]/split にアクセスします
2. 🖱️ 分割線を視覚的に調整します（ドラッグ、または Gemini AI の自動検出を利用）
3. ✅ 「Apply Split」をクリックします — 切り抜き座標を含む 2 つの仮想ページが作成されます
4. 📸 元の画像は保持され、切り抜き後の画像に対して OCR が実行されます

✍️ Gemini Batch API でバッチ OCR を実行する

POST /api/books/[id]/batch-ocr-async
{
  "page_ids": ["page-1", "page-2", "page-3"],
  "language": "la"
}

ジョブ ID が返されます。Gemini はオフラインで処理し、完了時に結果を保存します。標準 API より 50% 安価です。

🎓 学術版を生成する

POST /api/books/[id]/editions
{
  "title": "The Emerald Tablet: First Complete English Translation",
  "translator": "Jane Doe",
  "language": "en",
  "format": "epub"
}

システムは次のものを生成します：

• 📝 学術版の前付け（序文、翻訳者の略歴など）
• 📱 目次とメタデータを含む EPUB
• 🆔 Zenodo 連携による DOI
• 📚 引用メタデータ（BibTeX、RIS）

---

🧪 テスト

🚀 テストを実行する

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# End-to-end tests (Playwright)
npm run test:e2e

# Coverage report
npm run test:coverage

# Watch mode
npm run test:watch

✅ E2E テストの例

• 📥 書籍のインポート — IA 取り込みパイプラインを検証します
• ✂️ 分割検出 — ノド検出の精度を確認します
• 🌐 翻訳 — 原文と翻訳の対応を確認します
• 🔒 テナントのサブドメイン — コンテンツが分離され、漏えいがないことを確認します
• 🔍 検索 — 全文検索とセマンティックインデックスをテストします

---

🚀 デプロイ

🔄 ステージング（プレビュー）

プッシュされたブランチは、すべて Vercel のプレビュー環境に自動デプロイされます：

git push origin feat/my-feature
# ↓ Vercel builds and deploys
# ↓ Preview URL in GitHub PR

🌍 本番環境

PR 経由で main にマージすると、sourcelibrary.org に Vercel で自動デプロイされます

✅ デプロイ前チェックリスト：

• テストが合格する（npm run test）
• TypeScript のチェックが合格する（npx tsc --noEmit）
• ハードコードされたシークレットや認証情報がない
• テナントのサブドメインの漏えい監査が合格する（node scripts/audit-bph-leaks.mjs）
• PR がレビューされ、承認されている

🔑 環境変数

必須（.env.local）：

MONGODB_URI=mongodb+srv://...
NEXTAUTH_SECRET=<random-secret>
GOOGLE_API_KEY=<gemini-key>
VERCEL_BLOB_TOKEN=<vercel-blob-token>
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

任意：

STRIPE_SECRET_KEY=<for-donations>
ZENODO_TOKEN=<for-doi-minting>
SUPABASE_URL=<for-embeddings>

---

📖 ドキュメント

• 🗺️ システムマップ — 包括的なアーキテクチャ図とファイル索引
• 🏗️ ARCHITECTURE.md — データモデル、ワークフロー、設計上の決定
• 🤖 AGENTS.md — AI エージェントと自動化ワーカー向けの技術的なコンテキスト
• 📋 CLAUDE.md — 開発ワークフロー、PR の規約、重要な不変条件
• 🔐 AUTH_IMPLEMENTATION.md — NextAuth のセットアップとテナント認証
• 📦 バッチ OCR ワークフロー — Gemini Batch API の使用方法
• 🔌 API ドキュメント — REST API リファレンス
• 🖼️ 画像処理 — 切り抜きとサイズ変更の仕組み

---

🤝 コントリビューション

コントリビューションを歓迎します！まずは CONTRIBUTING.md をご確認ください — セットアップ、ブランチ／PR のワークフロー、デプロイの仕組み（および設定してはいけない Vercel の設定）、データ安全性のルールが記載されています。より詳しい方針は開発ワークフローに記載されています。要点は次のとおりです：

1. 🌿 機能ブランチを作成する（main から分岐）：

   # Using git worktree for multi-session safety
   git worktree add .claude/worktrees/feat-xyz feat/xyz
   cd .claude/worktrees/feat-xyz
   

2. ✏️ 変更を加えてテストする：

   npm run lint
   npm run test
   npm run test:e2e
   

3. 📤 プッシュして PR を作成する：

   git push origin feat/xyz
   gh pr create --base main
   

4. 📋 PR のガイドライン：

   • PR ごとに懸案事項は 1 つ — リファクタリングと機能をまとめないでください
   • 削除を確認する — コードを削除する前に必ず grep -rn を実行してください
   • 型チェックを実行する — 提出前に npx tsc --noEmit を実行してください
   • 範囲を説明する — 対象範囲と対象外の範囲の両方を明記してください

🎯 求めている貢献

• 🐛 テストカバレッジを伴うバグ修正
• ✨ プロジェクトのミッションに沿った機能の実装
• ⚡ ベンチマークを伴うパフォーマンスの改善
• 📝 ドキュメントの改善
• ♿ UX／アクセシビリティの向上
• 🏢 テナント統合の例

📢 問題の報告

• 🐛 バグ — 再現手順と、期待される動作と実際の動作を記載してください
• 💡 機能リクエスト — ユースケースとユーザーへの影響を説明してください
• ❓ 質問 — issue を作成してください

---

🛡️ セキュリティとデータ保護

• 🚫 承認なしの削除禁止 — 書籍やページを削除する場合は、必ず明示的な確認が必要です
• 🔒 テナントの分離 — テナントのサブドメインは閉じたシステムです（テナント間で情報が漏れることはありません）
• 🔐 シークレット管理 — すべてのシークレットは環境変数を使用し、ハードコードしないでください
• ⚖️ AGPL ライセンス — コントリビューションは AGPL-3.0-or-later を遵守する必要があります

セキュリティポリシーの詳細については、CLAUDE.md Securityを参照してください。

---

📊 現在の状況

2026 年 7 月時点 — 数値は毎週変動します。最新の数値はsourcelibrary.org/dataをご覧ください。

📈 アクティブなコーパス：

• 📚 visible: true の書籍が約 29K 冊
• ✅ 約 15K 冊を完全に処理済み（OCR と翻訳が完了）
• 🌍 約 14K 冊に英語の完全な翻訳あり
• 🖼️ ギャラリーにカタログ化された挿絵が 200K 点以上

⚙️ 処理能力：

• 📥 月に 15K ページ以上を取り込み
• 🗣️ 多言語に対応（ラテン語、ドイツ語、ギリシャ語、アラビア語、サンスクリット語、中国語など）
• 💰 コストを 50% 削減するバッチ API

🏢 プラットフォームのテナント：

• 🔮 Bibliotheca Philosophica Hermetica — ヘルメス文書と秘教資料
• ⚗️ Kloss Collection — 医学錬金術
• 🤝 追加のパートナーと開発中

---

📝 ライセンス

Source Library は、GNU Affero General Public License v3.0 or later（AGPL-3.0-or-later）に基づいてライセンスされています。すべてのコントリビューションはこのライセンスを遵守する必要があります。

サードパーティのライセンスと帰属表示の詳細については、LICENSING.mdを参照してください。

---

📞 サポートとコミュニティ

• 🐛 バグを見つけましたか？ issue を作成してください
• 🤝 共同で取り組みたいですか？ コントリビュートしてください
• 🌐 サイトを見る — sourcelibrary.org

---

src/
├── app/              # All routes, pages, and API endpoints
│   ├── api/          # API routes
│   ├── book/         # Book pages (detail, read, pipeline)
│   └── page.tsx      # Homepage
├── components/       # Reusable React components
├── hooks/            # Reusable React hooks for component logic
└── lib/              # Business Logic, Utilities (mongodb, ai, types), and Services