動作原理の概要

DevLingo の核心は、インテリジェントな「クエリ階層化」システムです。ローカルの高速クエリから始まり、段階的に AI 推論へとエスカレートします。これにより、ほとんどのクエリはミリ秒単位で完了し、複雑なクエリでも 2 秒を超えません。

完全なワークフロー

ユーザーが任意のアプリでテキストを選択
    ↓
[トリガー] ⌘⇧D ショートカットを押す
    ↓
[抽出] TextExtractor が取得：
    • 選択したテキスト自体
    • 前後 50 文字のコンテキスト（AI がコンテキストを理解するため）
    • 現在のアプリの bundleIdentifier（Xcode / Slack / GitHub など）
    ↓
[分類] InputTypeDetector が入力タイプを判定：
    • 日本語 → Express モード
    • 単語 → Word モード
    • 2〜4 語で文構造なし → Phrase モード
    • 完全な文 ≤20 語 → Sentence モード
    • 複数文または >20 語 → Paragraph モード
    ↓
[クエリ] LookupCoordinator による階層化クエリ（詳細は下記）
    ↓
[レンダリング] FloatingPanelController：
    • マウスの下に NSPanel フローティングウィンドウを表示
    • スケルトンスクリーン（ローディングアニメーション）を表示
    • モードに応じた View サブクラスを選択（WordView / PhraseView / SentenceView など）
    • データ到着後、スムーズにフェードインで結果を表示
    ↓
[インタラクション] ユーザーが以下を実行可能：
    • 再生ボタンをクリックして発音を聴く
    • 単語をクリックして再帰クエリ
    • 「単語帳」に保存（SwiftData）
    • フローティングウィンドウを閉じて作業を続行

クエリ階層化システム

これが DevLingo のパフォーマンスの鍵です。優先度順にクエリし、結果が見つかり次第返します：

第 1 層：ローカル技術語彙ライブラリ（<50ms）

英語入力の場合、まずローカル SQLite データベースでクエリします。85 以上の一般的な開発用語がプリセットされています：

idempotent, deployment, microservice, containerization,
latency, throughput, cache invalidation, API gateway,
circuit breaker, distributed tracing, ...

開発語彙クエリの約 30% にヒットします。超高速レスポンスです。

第 2 層：ローカル開発フレーズライブラリ（<100ms）

2〜4 語のフレーズの場合、ローカルフレーズデータベース（50 以上のプリセットフレーズ）でクエリします：

yak shaving, bikeshedding, rubber ducking, code smell,
low-hanging fruit, technical debt, nerd sniping, ...

フレーズクエリの約 20% にヒットします。

第 3 層：SwiftData キャッシュ（<10ms）

ユーザーが以前にクエリした語彙、フレーズ、文がすべてローカルの SwiftData にキャッシュされています。見つかった場合、直接返します。

ユーザーが "idempotent" をクエリ済み → 次回のクエリ <10ms

ヒット率は約 50%（使用履歴に依存）です。

第 4 層：Claude API（0.5〜2s）

前の 3 つの層でヒットしなかった場合、Claude API を呼び出して構造化されたレスポンスを取得します。

リクエスト：{
  "text": "gracefully degrade",
  "mode": "phrase",
  "context": "when upstream dependencies are unavailable",
  "sourceApp": "Xcode",
  "userLanguage": "ja"
}

レスポンス：{
  "type": "phrase", // compound verb
  "definition_en": "...",
  "definition_ja": "...",
  "examples": [...],
  "pronunciation": {...},
  "register": "technical",
  "l1_tips": "..."
}

:::note なぜ階層化設計なのか

• 95% の一般的な語彙が最初の 3 つの層にヒットし、<100ms で返します
• 5% のまれな語彙や新しい語彙だけが Claude API を必要とし、それでも 1〜2 秒です
• ネットワークがない場合でもローカルライブラリとキャッシュでクエリ可能
• ユーザーのクォータを節約 Claude API は使用回数に基づく課金で、階層化により 95% の API コールを削減 :::

バックエンドアーキテクチャ

DevLingo のバックエンドは Cloudflare Workers のエッジノードにデプロイされ、API リクエストを処理します。

Mac アプリ
  ↓ HTTPS (Bearer token)
Cloudflare Workers (Edge)
  ├─ API Gateway (Hono ルーティング)
  ├─ Auth Middleware (JWT 検証)
  ├─ Lookup Endpoint (/api/lookup)
  │   └─ Claude API Client (AI リクエストのプロキシ)
  ├─ TTS Endpoint (/api/tts)
  │   └─ Google Cloud TTS (発音合成のプロキシ)
  └─ Data Sync Endpoints
      └─ Cloudflare D1 (ユーザーデータベース)

主要コンポーネント

• Hono フレームワーク：軽量 HTTP フレームワーク、Cloudflare Workers 向けに最適化
• D1 データベース：Cloudflare 上の SQLite、ユーザーの単語帳と同期データを保存
• KV ストレージ：セッショントークン、レート制限キャッシュ、API レスポンスキャッシュ
• Claude API プロキシ：Mac アプリは Workers を経由して Claude へのリクエストをプロキシし、ローカルで API キーを露出させません

テキスト抽出とコンテキスト

TextExtractor は AXUIElement（macOS アクセシビリティ API）を利用して取得します：

ユーザーが Slack で選択："idempotent"

抽出結果：
{
  "selectedText": "idempotent",
  "beforeContext": "We need to make sure this endpoint is ",
  "afterContext": " for retry requests.",
  "sourceApp": "com.tinyspeck.slackmacgap",  // Slack
  "fullSentence": "We need to make sure this endpoint is idempotent for retry requests."
}

このコンテキストが Claude に送信され、AI が理解するのに役立ちます：「idempotent はここでは API 設計のコンテキストで使用されている」ということです。

入力タイプ検出アルゴリズム

if テキストに日本語が含まれる:
  → Express モード
elif 単語数 == 1:
  → Word モード
elif 単語数 in [2, 3, 4]:
  if 完全な文構造を含む:
    → Sentence モード
  else:
    → Phrase モード
elif 文数 > 1 or 単語数 > 20:
  → Paragraph モード
else:
  → Sentence モード

:::tip インテリジェント検出 入力検出はローカルで瞬時に完了し、API コールはありません。ユーザーが「入力タイプの判定」ステップの遅延を感じることは決してありません。 :::

フローティングウィンドウの表示

FloatingPanelController が NSPanel（フローティングウィンドウ）を作成します：

特性：
• すべてのアプリの上に表示（Level: screenSaver）
• 位置：マウスの真下（y offset +20px、遮らないように）
• 初期状態：スケルトンスクリーン（ローディングスケルトン）
• データ到着：フェードイン、スケルトンを破棄
• インタラクション：マウスを完全にパススルー（バックグラウンドアプリをブロックしない）
• 閉じる方法：外側をクリック、ESC を押す、5 分間操作がなければ自動的に閉じる

パフォーマンス目標

• ローカルライブラリクエリ：<50ms（99 パーセンタイル）
• キャッシュヒット：<10ms
• 完全なエンドツーエンド（API を含む）：<2s（99 パーセンタイル）
• フローティングウィンドウの表示時間：<300ms（ユーザーが感じる速さ）
• TTS 音声生成：初回 <2s、以降のキャッシュ <100ms

:::note キャッシュ戦略 TTS 音声もローカルと KV にキャッシュされ、同じ単語の発音は一度だけ合成されます。 :::

データプライバシー

ユーザーテキスト
  ↓
Mac アプリ (HTTPS 暗号化)
  ↓
Cloudflare Edge (即時処理)
  ├─ Claude API リクエスト（一時的、トレーニングには使用されない）
  └─ 結果を KV にキャッシュ（自動有効期限）
  ↓
結果を Mac に返す
  ↓
ローカル SwiftData に保存（デバイス内、オプションで D1 にクラウド同期）

テキスト内容は、ユーザーが意図的に単語帳に保存しない限り保存されません。詳しくはデータプライバシーとセキュリティをご覧ください。

DevLingo のアーキテクチャ設計理念は：「速度第一、AI は補助、プライバシー最優先」です。