---
name: metadata only + 外部 CDN fetch = scale 耐性高い設計 (2026-05-11)
description: ★★★★ 2026-05-11 STEP 1075 実装で確立. file 自体を保存せず metadata (URL + caption + license) のみ JSON 持つ → repo 軽量維持 + 数千 entry まで気軽に拡張可能 + license compliance 自動
type: feedback
originSessionId: 42f100d8-b702-4b4b-a14f-b23a9209d888
---
# Metadata Only + 外部 CDN Fetch 設計 (永続原則)

STEP 1075 (Wikimedia 微生物 gallery) で確立した永続設計原則.

## 原則

外部 OSS (Wikimedia / NASA / GBIF / arXiv 等) から media (画像/動画/音声) を取得する場合:

1. **ファイル自体は repo に保存しない**
2. **metadata (URL + caption + license + contributor) のみ JSON で保存**
3. **browser から直接 CDN fetch** (server proxy なし)

**Why**:
- repo size 増加が極めて軽量 (~600 B per entry)
- license compliance は metadata に記録するだけで満たせる (CC-BY/CC-BY-SA の attribution requirement)
- 最新情報自動反映 (CDN 側 update が即時 user に届く)
- offline は弱いが、 online 限定 PWA なら問題ない

**How to apply**:

新 lens / 新 data source 追加時:
1. fetch script で metadata のみ取得 → `data/<lens>/latest.json` 保存
2. 実 file URL は記録するが download しない
3. browser component で `fetch(url)` → `<img>` / `<video>` element に直接渡す
4. license / contributor を UI に必ず表示

## scale 上限 (実測 + 推定)

| 規模 | metadata size | JSON 単一 file | UI 表示 | 真の bottleneck |
|---|---|---|---|---|
| 100 entry | 60 KB | ✅ | ✅ grid | none |
| 1,000 | 600 KB | ✅ | ⭕ paginated | none |
| 10,000 | 6 MB | ⚠ split 推奨 | ⚠ search 必須 | UI render |
| 100,000 | 60 MB | ✗ DB 必要 | ✗ filter UI 必須 | **CDN 在庫** |
| 1,000,000+ | 600 MB+ | ✗ | ✗ | CDN 在庫 (Wikimedia 全 file 1.1億) |

**結論**: 真の上限は repo でなく **(1) UI render 性能 (~3000 entry) + (2) 元 CDN 在庫**.

## 適用既実装

| STEP | data source | metadata size | file 保存? |
|---|---|---|---|
| 1020 | OctaTheoria 4 domain (theory/arxiv/crypto/fx) | ~30 KB | ❌ (live API fetch) |
| 1046 | OctaTheoria +3 domain (LIGO/NASA/GBIF) | ~10 KB | ❌ |
| 1052 | LMFDB | ~2 KB | ❌ |
| 1075 | Wikimedia 微生物 10 種 | 6 KB | ❌ (Wikimedia CDN 直接) |

→ **全 lens で metadata only 設計 統一済**.

## 反 Pattern (やってはいけない)

- ❌ Wikimedia 動画を repo にコピー (license issue + repo bloat)
- ❌ NASA 画像を S3 / R2 に redistribute (帯域コスト)
- ❌ HuggingFace model 重み持ち込み (GB 単位)
- ❌ arXiv PDF を data/ に full save (~10 MB/paper)

→ 全て **「URL 記録 + browser 直接 fetch」** で代替可能.

## 例外 (ファイル保存が正当化される場合)

- ✅ 自前 generation した artifact (Verilog / Lean 4 / 論文 markdown 等)
- ✅ 公開 license + 永続性が必要な research data (Zenodo deposit との対応物)
- ✅ small lookup table (定数 / mapping) で repo readability に寄与するもの

## 関連

- `feedback_dictionary_datacenter_dual_vision.md` ★★★★★ — 「中身有り辞書 + データセンター両立」 vision との整合性
- `project_quantum_microscope_hub_complete_2026-05-11.md` (本日 operational evidence)
- STEP 1072 deploy fix incident protocol (`docs/SITE_COVERAGE_MAP.md`) — dist-renderer/index.html commit protocol