メインコンテンツまでスキップ
バージョン: 2025-11-18

0. アーキテクチャ設計

前提知識レベル:

  • C4モデルに関する基本的な理解
  • Webアプリケーションの一般的な構成（フロントエンド、バックエンド、DB）に関する知識

0.1. C4モデル​

本ドキュメントでは、システムの構造を段階的に理解しやすくするために「C4モデル」という考え方を採用し、概観（コンテキスト）から詳細（コンテナー）へと掘り下げて説明します。

0.1.1. コンテキスト図 (Context Diagram)​

システム全体の概観を示します。ユーザーがどのようにシステムとやり取りし、どの外部システムと連携するかを表します。

要素説明
ユーザーネットワークの可視化や分析を行う研究者や開発者。
Web Application本システムのコア機能を提供するWebアプリケーション。
LLM Servicesユーザーの指示解釈、ツールプランニング、応答生成のために利用する外部の大規模言語モデルサービス。

0.1.2. コンテナー図 (Container Diagram)​

アプリケーションを構成する主要なコンテナー（サービス）と、それらの間のデータの流れ、および利用技術を示します。

0.2. データ永続化​

本システムにおけるデータの永続化は、目的の異なる2つの仕組みによって実現されています。

  • サーバーサイド (Database):

    • 目的: アプリケーションのコアとなるデータを安全に保管し、ユーザーセッションを跨いで状態を維持する。
    • 技術: PostgreSQL
    • 永続化されるデータ:
      • ユーザーアカウント情報（ハッシュ化されたパスワードを含む）
      • 各ユーザーの会話履歴
      • メッセージ（ユーザーの発言、LLMの応答）
      • GraphMLデータ本体
      • ネットワークの永続的な属性データ（元データ由来、または計算によって追加されたレイアウト座標や中心性指標など）
    • 補足: 主要なテーブルの構造については、データベーススキーマ仕様で詳細を定義しています。

  • クライアントサイド (Web Browser):

    • 目的: ユーザーの利便性向上。再ログインの手間を省き、シームレスな認証状態を維持する。
    • 技術: HttpOnly属性を付与したCookie
    • 永続化されるデータ:
      • 認証用のJSON Web Token (JWT)
    • 役割: API Serviceが発行したJWTをブラウザがCookieとして安全に保存する。以降のAPIリクエストでは、ブラウザが自動的にCookieをリクエストヘッダーに含めて送信するため、クライアントサイドのJavaScriptがトークンにアクセスする必要はない。
    • セキュリティ: HttpOnly属性により、JavaScriptからのCookieへのアクセスが禁止されるため、XSS（クロスサイトスクリプティング）攻撃によるトークン窃取のリスクを大幅に軽減します。これは、localStorageを利用する方法よりも安全です。

0.3. リアルタイム通信方針​

サーバーからクライアントへの非同期な情報通知には、HTTP Streaming (Server-Sent Events) を利用する。

  • 採用理由:

    • シンプルさ: WebSocketのような双方向通信プロトコルは、今回の要件に対して過剰である。共同編集機能のようなクライアントからのリアルタイムな操作はスコープ外であり、サーバーからの一方向の通知で十分である。
    • 軽量さと実装の容易さ: SSEは標準的なHTTP上で動作するため、既存のインフラストラクチャとの親和性が高く、実装が容易である。クライアント側もブラウザ標準のEventSource APIで簡単に扱うことができる。
    • 要件への適合: LLMの思考プロセスのストリーミングや、計算完了通知といった現在の要件は、サーバーからクライアントへのプッシュ通知で完結する。SSEはこれらの要件を効率的に満たす。

  • 主な用途:

    • ネットワーク操作（計算・可視化適用）の完了通知と、更新されたレンダリングデータの送信。
    • 大規模ネットワークにおけるレイアウト計算などの進捗通知。
    • LLMの思考プロセスやツール実行状況のストリーミング。

この決定は、「実装を不必要に複雑にしない」という全体方針に合致する。

0.4. 非機能要件​

0.4.1. パフォーマンス​

  • LLM連携処理 (/chat/process):
    • 目標: ユーザーのメッセージ受信からLLMの最終応答（ストリーミング終了）までの中央値を5秒とする。
    • 補足: この時間は外部LLMサービスの応答時間に大きく依存するため、あくまで目標値とする。

0.4.2. 可用性​

  • 目標稼働率: 99.5%
  • メンテナンス: 定期メンテナンスは事前に通知の上、週末の深夜帯に実施する。

0.4.3. 拡張性​

  • ステートレス設計: APIサービスおよびNetworkXAPIは、セッション情報や計算結果といった状態をサービスインスタンス内に保持しません。すべての状態は外部のデータベースに集約・永続化されるため、各サービスはステートレスなコンポーネントとして動作します。これにより、コンテナーの水平スケールアウトを容易に実現します。
  • 非同期処理: 時間のかかるネットワーク計算（大規模なレイアウト計算など）は、バックグラウンドで非同期に処理し、完了を**Server-Sent Events (SSE)**でクライアントに通知するアーキテクチャを採用します。

0.4.4. セキュリティ​

  • 認証: 認証仕様で定義されたJWTとHttpOnly Cookieによるセキュアな認証方式を実装する。
  • データ保護: パスワードはハッシュ化して保存し、平文では保持しない。
  • 脆弱性対策: 主要なWeb脆弱性（XSS, CSRF, SQLインジェクション）に対する基本的な対策をフレームワークの機能を用いて実施する。