component-details

3. コンポーネント詳細

3.1. フロントエンド (Client)

• 責務:
  • ユーザーインターフェース (UI) の提供(チャット画面、可視化描画エリア)。
  • ユーザー認証(ログイン/ログアウト)のインターフェース。
  • グラフデータ(CSV, JSONなど)のアップロード。
  • チャットメッセージの入力とバックエンドへの送信 (WebSocket)。
  • バックエンドから受信した描画データ(JSON)に基づくグラフの描画・更新。
• 技術選定:
  • 可視化ライブラリ: D3.js を推奨する。描画自体に複雑な計算を必要とせず、高い柔軟性と表現力を提供するため。NetworkXで処理されたグラフデータは、標準的なJSON形式（node-linkデータなど）に変換することでD3.jsで容易に描画可能である。D3.jsのモジュールとしては、力指向性レイアウト (d3-force)、ズーム・パン操作 (d3-zoom)、SVGまたはCanvasレンダリング (d3-selection, d3-shape) などを活用する。ただし、D3.jsはWebGLベースのSigma.jsと比較して、数万ノード規模の大規模グラフの描画にはパフォーマンス面で不向きであるという点に留意する必要がある。もし将来的に大規模グラフの描画が必要になった場合、パフォーマンス上のボトルネックとなる可能性があり、その際はSigma.jsのようなWebGLベースのライブラリへの移行、またはD3.jsとWebGLレンダリングを組み合わせるなどの検討が必要になる。
• 状態同期とUI:
  • リアルタイム同期: バックエンドとの状態同期には WebSocket を用いる。ブラウザのネイティブWebSocket API、またはsocket.io-clientのようなライブラリを使用し、バックエンドが状態の「信頼できる唯一の情報源(Source of Truth)」となる。
  • 効率的なデータ転送: 状態更新時には、状態オブジェクト全体ではなく JSON Patch (RFC 6902) 形式で差分のみを送信し、ネットワーク帯域を効率化する。クライアントサイドではfast-json-patchなどのライブラリでパッチを適用する。
  • ユーザーエクスペリエンス: オプティミスティックUI を採用。ユーザー操作を即座にUIに反映させ、バックエンドからの確定情報を待つことで、体感的な応答性を向上させる。バックエンドからの確定情報とローカルの状態を比較し、必要に応じて調整するロジックを実装する。

3.2. バックエンド (Backend)

• フレームワーク: FastAPI
  • 選定理由: ネイティブな非同期サポートにより、HTTPリクエスト、WebSocket接続、非同期タスクキュー(Celery)といった複数のI/Oバウンド処理を単一イベントループ内で効率的に並行処理できる。API中心のアーキテクチャに最適であり、自動APIドキュメント生成やPydanticによる厳格な型検証機能が開発効率と堅牢性を高める。
  • 技術詳細: Starletteを基盤とし、Pydanticによるデータ検証・シリアライズ、依存性注入 (Dependency Injection) によるクリーンなコード構造、OpenAPI (Swagger UI/ReDoc) による自動APIドキュメント生成が特徴。非同期処理にはasync/await構文を全面的に採用。

A. APIゲートウェイ (API Gateway)

• 責務:
  • フロントエンドからのすべてのリクエスト(HTTPおよびWebSocket)の単一窓口。
  • リクエストの認証(認証サービスと連携)。
  • リクエスト内容に基づき、適切な内部サービスに処理をルーティングする。
• 技術詳細: FastAPIのルーター (APIRouter) を用いてエンドポイントを定義し、ミドルウェア (Middleware) を活用して認証処理や共通のヘッダー処理などを実装する。WebSocket接続もFastAPIのネイティブサポートにより効率的に管理される。

B. 認証サービス (Auth Service)

• 責務:
  • ユーザー登録、ログイン、ログアウト処理。
  • JWT (JSON Web Token) を用いたセッショントークンの発行と検証。
• 認証フロー:
  • アクセストークン: 短命(例: 15分)のJWT。APIリクエスト時にAuthorizationヘッダーで送信。
  • リフレッシュトークン: 長命(例: 7日)のトークン。安全なHttpOnlyクッキーに保存し、XSSによるトークン盗難リスクを緩和する。
• トークン失効:
  • JWTはステートレスなため、本質的に失効が困難である。この対策として、失効したリフレッシュトークンのIDをRedisのブラックリストで管理する。python-joseライブラリでJWTの生成・検証を行い、passlibでパスワードのハッシュ化を行う。Redisクライアント (redis-py) を使用して、リフレッシュトークンのJTI (JWT ID) をRedisのセットに保存し、失効チェックを行う。

C. チャット / LLMサービス (Orchestrator)

• 責務:
  • システムの中核。ユーザーの自然言語指示をLLMが直接解釈し、可視化結果に反映させるための必要な処理をオーケストレーションする。
  • LLM Function Calling を活用し、ユーザーの意図を具体的な関数呼び出しに変換する。
  • フロントエンドからのチャットメッセージを受信 (WebSocket)。
  • LLM API（例: Gemini）に対し、プロンプト（会話履歴、Function定義）とユーザーメッセージを送信する。
  • LLMの応答（テキストまたはFunction Call要求）を処理する。
• LLM連携フロー:
  1. ユーザーのクエリと定義済み関数スキーマをLLMに送信。関数スキーマはPydanticモデルで厳密に定義し、LLMに提供する。
  2. LLMが返すJSON(呼び出すべき関数と引数)を解析・検証。Pydanticモデルによる厳格なバリデーションを適用する。
  3. 対応する内部サービス(計算サービス、状態管理サービス)を呼び出す。
• プロンプトエンジニアリング:
  • 曖昧な指示の推測と明確化:
    • 「友達が多い人」→「次数中心性」、「橋渡しになっている人」→「媒介中心性」のように、曖昧な指示でも特定のグラフ指標に推測可能な場合は、LLMが自動的に推測し可視化に反映する。
    • 一方、「重要なノード」のような推測が困難な真に曖昧な指示に対し、LLMが明確化のための質問 (例: 「重要性を判断する指標はどれですか？」) を返すようにプロンプトを設計する(Ask-when-Needed)。
  • 複雑なタスクには、思考の連鎖(Chain-of-Thought)を促し、複数の関数呼び出しを計画・実行させる。
• セキュリティ:
  • LLMが生成した関数呼び出しは信頼できない入力として扱う。実行前に、関数名のホワイトリスト検証、引数の型・値の厳格な検証(Pydanticモデル使用)、入力のサニタイズを徹底する。

D. 計算サービス (Compute Engine)

• 責務:
  • NetworkXライブラリを用いて、ネットワーク分析(各種中心性、コミュニティ検出)やレイアウト計算など、計算負荷の高い処理を実行する。
• 非同期タスク処理:
  • Celery とメッセージブローカー RabbitMQ を使用。CeleryタスクはPython関数として定義され、@app.taskデコレーターでマークされる。タスクの実行結果はRedisを結果バックエンドとして利用し、永続化される。
  • Orchestratorからのリクエストを受け、計算タスクを即座にキューに投入。APIサーバーのブロッキングを防ぐ。
  • 計算完了後、結果を**計算結果DB (Redis)**に保存し、必要に応じてWebSocket経由で完了通知を送信する。

E. 可視化状態管理サービス (State Manager)

• 責務:
  • プロジェクトごとに現在の「可視化設定(マッピング状態)」を管理する。
  • Orchestratorからの要求に基づき状態を更新し、フロントエンド向けの最終的な描画用JSONを生成してプッシュする。
• リアルタイム同期アーキテクチャ:
  • 水平スケーリングに対応するため、WebSocket接続状態の管理には Redis Pub/Sub を利用する。FastAPIのWebSocketクラスで接続を管理し、redis-pyライブラリでPub/Subメッセージングを行う。
  • 状態変更時、特定のチャンネルに更新情報をPublish。全サーバーインスタンスがこれをSubscribeし、担当するクライアントに情報を届けることで、サーバー間での状態同期を実現する。
  • わずかな変更のたびに可視化状態オブジェクト全体を送信するのは非効率なため、jsonpatchライブラリなどを用いて旧状態と新状態の差分（「パッチ」）を計算し、この小さなパッチのみをWebSocket経由で送信する。

3.3. データストア (Data Persistence)

本システムは、データの特性に応じて複数のデータベースを使い分けるポリグロット永続化戦略を採用する。

Neo4j (グラフデータベース)

• 役割: グラフのトポロジー（ノード、エッジ、およびそれらの内在的プロパティ）の「信頼できる唯一の情報源（Source of Truth）」として機能する。
• 保存されるデータ: ユーザーがアップロードしたグラフのノード、エッジ、およびそれらのプロパティ。
• 永続化の仕組み: ユーザーがグラフデータをアップロードすると、バックエンドがデータを解析し、Neo4jにノードとリレーションシップとして投入する。Pythonのneo4jドライバーを使用してCypherクエリを実行し、グラフデータを操作する。これにより、グラフ構造のネイティブな保存と、Cypherによる効率的なトラバーサルおよびパターンマッチングクエリが可能となる。NetworkXはメモリ内計算エンジンとして利用され、Neo4jから取得したデータでグラフオブジェクトを構築する。

Redis (インメモリデータストア / メッセージブローカー)

• 役割: 高速キャッシュ層およびメッセージブローカーとして機能する。
• 保存されるデータ:
  • 計算済みメトリクスとレイアウト座標: NetworkXで計算された中心性スコアやレイアウト座標などの派生データ。これらはproject:{project_id}:graph:{graph_id}:metric:betweennessのようなキーで保存され、再計算コストを削減し、高速な取得を可能にする。ハッシュ (HSET) や文字列 (SET) などのデータ構造を利用する。
  • WebSocket接続状態: 複数のバックエンドインスタンス間でのWebSocket接続状態の管理。Redis Pub/Subをメッセージバスとして利用し、ユーザー固有のチャネル（例：channel:user_id:{user_id}）を通じて状態変更をPublish/Subscribeする。
  • JWT失効リスト: JWTアクセストークンのステートレス性に対応するため、失効したリフレッシュトークンのIDをRedisのブラックリストで管理する。セット (SADD) や文字列 (SET) とTTL (EXPIRE) を利用する。
• 永続化の仕組み: Pythonのredis-pyクライアントを使用してRedisと連携する。計算結果はCeleryワーカーによってRedisに直接書き込まれる。WebSocketの状態管理ではPub/Sub機能が利用され、JWT失効リストはTTL（Time to Live）を設定して管理される。サブミリ秒のレイテンシでのデータ読み書きが強み。

PostgreSQL (リレーショナルデータベース)

• 役割: アプリケーションのプライマリデータベースとして、構造化されたリレーショナルデータを管理する。
• 保存されるデータ: ユーザーアカウント、プロジェクトメタデータ、認証情報、保存された可視化設定、チャット履歴。
• 永続化の仕組み: ユーザー登録、プロジェクト作成、設定変更、チャット履歴の保存などの際に、ACID準拠のトランザクションを通じてデータが永続化される。FastAPIでは、SQLAlchemyやTortoise ORMなどのORM（Object-Relational Mapper）とasyncpgのような非同期ドライバーを組み合わせて利用し、データベース操作を行う。強力なデータ整合性とトランザクションの信頼性が強み。

  テクノロジー	プライマリデータモデル	アーキテクチャにおける役割	保存されるデータ	主な強み	主な弱点
  Neo4j	プロパティグラフ	グラフのトポロジーの永続的ストレージ	ノード、エッジ、およびそれらの内在的プロパティ	グラフ構造のネイティブな保存と、Cypherによる効率的なトラバーサルおよびパターンマッチングクエリ。	複雑な集計やトランザクション処理には不向き。
  Redis	キーバリュー	高速キャッシュ層およびメッセージブローカー	計算済みメトリクス、レイアウト座標、WebSocket接続状態、タスクキュー、JWT失効リスト。	サブミリ秒のレイテンシでのデータ読み書き。Pub/Sub機能によるスケーラブルな状態同期。	インメモリのため永続性は限定的。複雑なクエリは不可能。
  PostgreSQL	リレーショナル	アプリケーションのプライマリデータベース	ユーザーアカウント、プロジェクトメタデータ、認証情報、保存された設定、チャット履歴。	ACID準拠による強力なデータ整合性とトランザクションの信頼性。成熟したエコシステム。	グラフのような高度に接続されたデータのクエリは非効率。