Curigor

学んだことを AI に説明すると、AI の問い返しで分かっていない所が見つかる学習アプリ。対話からノートと復習の日程を作る。

curigor.com

概要

学んだ知識を自分の言葉で説明する機会が少ないと、記憶はすぐに抜けていきます。Curigor は「人に教えることで学ぶ（プロテジェ効果）」を AI との対話にしたアプリです。学んだことを説明すると AI が深掘りの質問を返し、それに思い出して答えることで、理解の穴が見つかり、知識が整理されます。

企画から設計・実装・テスト・インフラ・運用・法令対応（利用規約・プライバシーポリシー・アカウント削除）まで 1 人で担当しています。実装には主に Claude Code を使い、一部で Codex も使いました。仕様と設計の判断・レビューは自分で行っています（AI に渡している規約は CLAUDE.md と .claude/rules/）。本番は Vercel（client）と Railway（server・DB・ストレージ）で動いています。

主な機能

• 説明して学ぶ: 学んだことを AI に説明すると、AI が抜けや誤りを問い返す。終わるとノートとフィードバックができる
• 教わって理解する: 知らないことを疑問から教わり、観点・用語・要約を学習メモに残す
• 復習: 間隔を空けた日程で、ノートを見ずに説明し直す。説明の結果でノートと次の復習日が変わる
• 振り返り: その日・その週に終えた学習の要点とつまずいた所を 1 ページにまとめる。音声で聞くことも、小テストで確かめることもできる
• まとめノート: 関連するノートを束ね、ノート同士のつながりを候補として示す
• 声で話す: 話して説明し、応答を読み上げで聞ける。画像の添付・数式・コードにも対応

設計で判断したこと

ADR	課題	決めたこと
006	LLM の応答の良し悪しを何で判定するか	Langfuse は保管と閲覧だけに使い、判定の基準（golden・criterion）と judge はコードと YAML で持つ
018	LLM の費用を利用者ごとに抑える	操作ごとの 1 日の回数を Postgres で数える。記録は LLM を呼ぶ前に行い、失敗や切断でも返さない（返すと上限を抜けられる）
017	デプロイ後に古いタブが新しい server と話す	エラーに機械が読む code を持たせ、WebSocket の接続時に版を確かめて、合わなければ入力中の文を残して読み直す。REST の URL に版は付けない
016	アカウント削除で消すべきデータが外部にもある	削除専用の JWT で server を呼び、チェックポイント・画像・Langfuse の trace まで消す。論理削除はしない
021	振り返りの費用を、振り返る日の分だけにする	本文は LLM を使わず既存のノートから組み立てる。音声と小テストは押したときだけ生成し、内容のハッシュでキャッシュする（キャッシュのときは上限に数えない）
010	声で話すときの送信と割り込み	沈黙ではなく末尾の「以上」で送る。読み上げは PCM をストリーミングし、話し始めたら止める

ほかの判断は docs/adr/（21 本）。

品質の仕組み

• LLM の応答の eval: 説明への問い返しの失敗パターン 17 種を golden にし、LLM judge で回帰を確かめる。judge 自体も人間のラベルとの一致で測る（server/evals/）
• テスト: server の unit テストは実 PostgreSQL に接続し（DB のモックは使わない）、カバレッジが 75% を下回ると CI を落とす。他人のリソースに届かないことを REST・WebSocket の両方でテストする
• CI: ruff・mypy（strict）・pytest・ESLint・tsc・next build・Vitest・Gitleaks を PR ごとに通す。CodeQL と Trivy（本番のイメージ）で脆弱性を調べ、依存は Dependabot で毎週更新する

---

目次

• アーキテクチャ
• 技術スタック
• LangGraph フロー
• セットアップ
• 開発
• テスト
• ディレクトリ構造
• ドキュメント

---

アーキテクチャ

graph TB
    subgraph Vercel["Vercel"]
        Client["client (Next.js 16)\nBetterAuth（メール OTP / Google）\nチャット UI・ノート・復習"]
    end

    subgraph Railway["Railway"]
        subgraph Server["server (FastAPI)"]
            JWT["JWT 検証（JWKS）"]
            WSChat["/ws/chat → LangGraph"]
            REST["REST API"]
        end
        DB[("PostgreSQL 17 + pgvector\nノート・復習・チェックポイント")]
        Bucket[("Buckets（S3 互換）\n添付画像・アバター")]
    end

    OpenAI["OpenAI\n対話・埋め込み・文字起こし・読み上げ"]
    Langfuse["Langfuse\nトレース・eval の保管"]

    Client <-->|WebSocket| WSChat
    Client <-->|REST + JWT| REST
    Server --> DB
    Server --> Bucket
    Server --> OpenAI
    Server -.-> Langfuse

技術スタック

フロントエンド

カテゴリ	技術	用途
フレームワーク	Next.js 16 (App Router) + React 19	SSR/RSC 対応のフルスタックフレームワーク
言語	TypeScript (strict)	型安全なフロントエンド開発
認証	BetterAuth	メール OTP・Google ログイン / セッション管理
WebSocket	カスタム Hook (use-chat-websocket)	サーバーとの双方向リアルタイム通信
UI	shadcn/ui + Tailwind CSS	コンポーネントライブラリ
Markdown	react-markdown	LLM 応答のレンダリング

バックエンド

カテゴリ	技術	用途
言語	Python 3.13	-
Web フレームワーク	FastAPI + Uvicorn	WebSocket / REST エンドポイント
LLM オーケストレーション	LangGraph + LangChain	学習フローの状態管理・ルーティング
LLM	OpenAI（server/graph/llm.py でタスクごとに選ぶ）	対話・ノート生成・フィードバック
音声・埋め込み	OpenAI の文字起こし・読み上げ・埋め込み	声で話す・ノートのつながりの候補
ストレージ	S3 互換（aiobotocore）	添付画像・アバター
観測・eval	Langfuse + 自前の eval（server/evals/）	トレース・応答の回帰の確認
認証検証	PyJWT + JWKS	BetterAuth 発行 JWT の公開鍵検証
パッケージ管理	uv	依存関係管理

データベース

カテゴリ	技術	用途
RDBMS	PostgreSQL 17 + pgvector	全データの永続化・ノートの埋め込みの近傍検索
データアクセス	asyncpg + 生 SQL	SQL ファーストアプローチ（ORM 不使用）
チェックポイント	langgraph-checkpoint-postgres	LangGraph フロー状態の永続化
マイグレーション	Alembic	スキーマバージョン管理

LangGraph フロー

route_entry（session_type で入口を分ける）
  ├─ "learning"  → learning_start  → learning_dialogue（ループ） → generate_note → generate_feedback → END
  ├─ "review"    → review_start    → review_dialogue（ループ）   → update_note_and_feedback → END
  ├─ "synthesis" → synthesis_start → synthesis_dialogue（ループ）→ finish_synthesis → END
  └─ "explore"   → explore_start   → explore_dialogue（ループ）  → generate_study_memo → END

• learning: 説明して学ぶ。対話の後にノートとフィードバック（理解度・良かった点・改善点）を作る
• review: 復習。ノートを見ずに説明し直し、ノートとフィードバックを更新する
• synthesis: まとめノートに束ねたノートを横断してまとめる
• explore: 教わって理解する。対話から学習メモを作る

技術選定の背景・比較検討・トレードオフは docs/adr/ を参照。

---

セットアップ

前提条件

• Docker / Docker Compose
• Node.js 24+
• Python 3.13+
• uv

初回セットアップ

# 1. リポジトリをクローン
git clone <repo-url>
cd curigor

# 2. 環境変数を設定
cp .env.example .env                      # POSTGRES_PASSWORD 等を記入（未設定だと docker compose が起動しない）
cp server/.env.example server/.env        # OPENAI_API_KEY 等を記入
cp client/.env.example  client/.env.local # BETTER_AUTH_SECRET 等を記入

# 3. 依存関係のインストール・DB 構築・マイグレーションを一括実行
make setup

This is the beginning of the README. Read the rest at the original. Read the full README ↗