メインコンテンツまでスキップ
バージョン: design-archive

詳細設計

本ドキュメントは、基本設計で定義されたシステム構成、機能、データ構造に基づき、各コンポーネントの内部構造、アルゴリズム、インターフェースの具体的な実装レベルの設計を記述する。主に開発者を対象とし、実装に必要な詳細情報を提供する。

1. Orchestrator / LLM Service​

1.1. モジュール/クラス構造​

  • orchestrator.py: メインのオーケストレーションロジック、WebSocketハンドリング。
  • llm_client.py: Gemini APIとの通信インターフェース、プロンプト構築。
  • function_registry.py: LLMに提供するFunction Callingのスキーマ定義と、対応する内部関数のマッピング。
  • prompt_builder.py: 会話履歴、利用可能なツール、ユーザー指示に基づいたプロンプト生成ロジック。

1.2. 主要アルゴリズムとロジック​

  • Function Callingの解析と検証: LLMからのFunction Call応答（JSON）をPydanticモデルで厳格に検証し、不正な呼び出しを拒否するロジック。
  • 曖昧性解消ロジック: ユーザーの指示が曖昧な場合に、LLMに明確化を促すプロンプトを生成するロジック（Ask-when-Needed）。
  • 推測ロジック: 曖昧な指示でも推測可能な場合に、適切なグラフ指標や可視化プロパティを決定するロジック。
  • タスクディスパッチ: LLMが決定したFunction CallをCompute EngineやState Managerに非同期で依頼するロジック。

1.3. 詳細インターフェース仕様​

  • LLM APIとのインターフェース: Gemini APIのSDKを利用した具体的なリクエスト/レスポンスのデータ構造、エラーハンドリング。
  • 内部サービスとのインターフェース: Compute EngineへのCeleryタスクディスパッチの具体的な引数、State Managerへの状態更新リクエストのデータ構造。

2. Compute Engine​

2.1. モジュール/クラス構造​

  • tasks.py: Celeryタスクとして実行されるグラフ分析関数（例: calculate_degree_centrality, detect_communities）。
  • graph_loader.py: Neo4jからグラフデータをNetworkXオブジェクトとしてロードするロジック。
  • metric_calculator.py: NetworkXを用いた各種中心性、コミュニティ検出アルゴリズムの実装。
  • layout_calculator.py: Force-directedなどのレイアウトアルゴリズムの実装。

2.2. 主要アルゴリズムとロジック​

  • グラフデータロード: Neo4jのCypherクエリを用いた効率的なデータ取得とNetworkXグラフ構築。
  • 中心性計算: NetworkXのdegree_centrality, betweenness_centrality, eigenvector_centralityなどの具体的な呼び出しと結果処理。
  • レイアウト計算: d3-forceアルゴリズムのPython実装または類似ライブラリの利用、座標の正規化。
  • 結果の永続化: 計算結果をRedisに効率的に保存するデータ構造とロジック。

3. State Manager​

3.1. モジュール/クラス構造​

  • state_manager.py: プロジェクトごとの可視化状態を管理するクラス。
  • json_patch_generator.py: 旧状態と新状態の差分をJSON Patch形式で生成するロジック。
  • websocket_publisher.py: Redis Pub/Subを介してWebSocketクライアントに更新をプッシュするロジック。

3.2. 主要アルゴリズムとロジック​

  • 状態更新: Orchestratorからのリクエストに基づき、内部の可視化状態オブジェクトを更新するロジック。
  • 描画JSON生成: 現在の可視化状態、Neo4jからの基本データ、Redisからの計算結果をマージし、フロントエンド向けの描画JSONを生成するロジック。
  • JSON Patch生成: jsonpatchライブラリを用いた差分計算の具体的な実装。
  • WebSocketメッセージング: Redis Pub/SubチャネルへのPublish/Subscribeの具体的な実装。

4. Auth Service​

4.1. モジュール/クラス構造​

  • auth_service.py: ユーザー登録、ログイン、ログアウトのビジネスロジック。
  • jwt_manager.py: JWTの生成、検証、リフレッシュトークン管理。
  • password_hasher.py: パスワードのハッシュ化と検証。

4.2. 主要アルゴリズムとロジック​

  • JWT生成と検証: python-joseライブラリを用いた具体的な実装、アクセストークンとリフレッシュトークンのライフサイクル管理。
  • リフレッシュトークン失効: Redisを用いたブラックリスト管理の具体的な実装。
  • パスワードハッシュ化: passlibライブラリを用いたセキュアなハッシュ化（例: bcrypt）。

5. テストケース設計​

各コンポーネントおよび機能に対して、以下のレベルでテストケースを設計する。

  • 単体テスト (Unit Test): 各モジュール、クラス、関数の最小単位での動作を検証する。
  • 結合テスト (Integration Test): コンポーネント間のインターフェースや連携が正しく機能するかを検証する。
  • システムテスト (System Test): システム全体が要件通りに動作するかを検証する。特にLLM連携による自然言語からの可視化変更フローを重点的にテストする。
  • パフォーマンステスト: 非機能要件で定義されたパフォーマンス要件を満たすか検証する。
  • セキュリティテスト: 認証・認可、入力検証、LLMからの出力検証など、セキュリティ関連の脆弱性がないか検証する。