Architecture
構成
| 場所 | 責務 |
|---|---|
.devcontainer/ |
再現可能な開発・検査環境 |
.github/ |
Issue、Pull Request、GitHub Actions |
agent/ |
専用エージェント（Goose）のRecipe等の構成（0002） |
config/ |
公開可能なサンプル設定とprofile雛形 |
docs/ |
製品仕様、設計、タスク、判断記録 |
packages/ |
Python CLIとライブラリ |
scripts/ |
ローカルとCIで共有する操作 |
templates/ |
Paper-Wiki、News-Wiki、新聞風PDFの雛形 |
web/ |
Quartz/Fumadocs等のWeb表示層 |
workers/ |
PDF/OCR/組版workerのDocker定義 |
設計原則
- 操作はMakefileへ集約し、人間、AI、CIが同じコマンドを使う。
- 依存関係は利用する段階で追加し、バージョン固定方針を記録する。
- 公開APIや保存形式の変更は、実装前に
docs/decisions/へ判断を残す。 - 正本はMarkdown、YAML frontmatter、取得ログ、原資料へのリンクにする。
- PDF原本、APIキー、Zotero実データ、個人資料、大学資料をリポジトリへ入れない。
- 外部サービスを再実装せず、API client、変換worker、表示層を薄く接続する。
- 単一ホストでも、VPS/Mac mini/RTX workerへ分散しても動く構成にする。
- サイトはWCAG 2.2 レベルAA相当を満たし、デザイン参考にデジタル庁デザインシステム （DADS）を用いる（0003）。
技術スタック
| 領域 | 採用候補 |
|---|---|
| Python依存管理 | uv |
| CLI | Typer |
| 型と設定検証 | Pydantic |
| HTTP/API | httpx |
| RSS/Atom | feedparser |
| Zotero | pyzotero |
| Markdown frontmatter | python-frontmatter / PyYAML |
| 状態DB・行動ログ受け皿 | SQLite、DuckDB、sqlite-utils（0009） |
| PDF→Markdown | Docling、Marker、MinerU、ndlocr-lite worker |
| Web Wiki | Fumadocs（採用、0001） |
| Dashboard | Next.js、shadcn/ui、Motion、Lenis |
| 専用エージェント基盤 | Goose（採用、0002） |
| LLM-Wiki生成 | archive/へ退避） |
| 引用ネットワーク展開 | OpenAlex API直叩き＋Zotero relations（自前実装、scripts/citation-network.py。Research Rabbit等の第三者SaaSに研究テーマを渡さない） |
| 仮説統計検証 | Quarto + R（採用、0007） |
| 自律リサーチ/RAG | DeepTutor（採用、0008） |
| 知識の構造化 | Hyper-Extract → Obsidianエクスポート（採用、0008） |
| 原本アーカイブ | Cloudflare R2（採用、0008） |
| 日本語OCR | NDLOCR-Lite（採用、0008） |
| DBビュー | Baserow、NocoDB |
| 監視・行動ログダッシュボード | Quarto dashboard静的方式（採用）、Grafanaは保留（0009） |
| PDF組版 | Vivliostyle、Paged.js、Quarto、Typst |
| 常駐・重い処理 | Docker Compose profiles |
実行profile
compose.ymlはprofileで役割を分ける。
| profile | 役割 |
|---|---|
local |
1台でCLI、Web、PDF worker、DBを動かす |
vps |
Dashboard、metadata DB、RSS/API取得、軽いjob queue、専用エージェント（0002）、DeepTutor常駐・収集・構造化（0008） |
mac-mini |
Zotero、Obsidian Sync、原本の作業コピー（正典はR2、0008）、軽いPDF変換、embeddings推論 |
rtx-worker |
OCR、Marker/MinerU/Docling、画像処理、ローカルLLM |
Makefileは次の形を目標にする。
make install
make doctor
make up PROFILE=local
make fetch PROFILE=vps
make convert PROFILE=mac-mini
make ocr PROFILE=rtx-worker
make newspaper PROFILE=vps