バージョン: 2025-11-14

LLMGraphvis 開発者ガイド

概要

このガイドは、LLMGraphvisプロジェクトの開発者向けに、開発環境のセットアップ、コーディング規約、テスト方法、デプロイ方法などを説明します。

プロジェクト構造

LLMGraphvisプロジェクトは、以下の主要なコンポーネントで構成されています。

LLMGraphvis/
  ├── API/                # バックエンドAPI
  │   ├── models/         # データベースモデル
  │   ├── schemas/        # APIスキーマ
  │   ├── routers/        # APIルーター
  │   ├── services/       # サービス
  │   └── core/           # コア機能
  │
  ├── NetworkXMCP/        # ネットワーク分析サービス
  │   ├── api/            # APIエンドポイント
  │   ├── database/       # データベース関連
  │   ├── graphml/        # GraphML処理
  │   ├── tools/          # ネットワーク処理ツール
  │   ├── layouts/        # レイアウトアルゴリズム
  │   ├── metrics/        # 中心性指標計算
  │   ├── cache/          # キャッシュ管理
  │   └── core/           # コア機能
  │
  ├── common/             # 共通モジュール
  │   ├── models/         # 共通モデル
  │   ├── utils/          # 共通ユーティリティ
  │   ├── exceptions/     # 共通例外
  │   └── logging/        # 共通ロギング
  │
  ├── frontend/           # フロントエンド
  │   ├── public/         # 静的ファイル
  │   └── src/            # ソースコード
  │
  ├── specification/      # 仕様書
  └── Sample/             # サンプルデータ

主要なモジュールの責務

API

models/: データベースモデルの定義
schemas/: APIリクエスト/レスポンススキーマの定義
routers/: APIエンドポイントの定義
services/: ビジネスロジックの実装
core/: コア機能（認証、エラーハンドリングなど）

NetworkXMCP

api/: APIエンドポイントの定義
database/: データベース関連の処理
graphml/: GraphML処理の実装
tools/: ネットワーク処理ツールの実装
layouts/: レイアウトアルゴリズムの実装
metrics/: 中心性指標計算の実装
cache/: キャッシュ管理の実装
core/: コア機能（エラーハンドリングなど）

common

models/: 共通モデルの定義
utils/: 共通ユーティリティの実装
exceptions/: 共通例外の定義
logging/: 共通ロギングの実装

開発環境のセットアップ

前提条件

Python 3.9以上
Node.js 16以上
Docker
Docker Compose

ローカル開発環境のセットアップ

リポジトリのクローン

git clone https://github.com/yourusername/LLMGraphvis.git
cd LLMGraphvis

環境変数の設定

cp .env.example .env

.envファイルを編集して、必要な環境変数を設定します。

バックエンドのセットアップ

# APIのセットアップ
cd API
python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate
pip install -e .

# NetworkXMCPのセットアップ
cd ../NetworkXMCP
python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate
pip install -e .

フロントエンドのセットアップ

cd ../frontend
npm install

データベースのセットアップ

cd ..
./run_postgres_local.sh

サービスの起動

# APIの起動
cd API
uvicorn main:app --reload --port 8000

# NetworkXMCPの起動
cd ../NetworkXMCP
uvicorn main:app --reload --port 8001

# フロントエンドの起動
cd ../frontend
npm run dev

Docker環境のセットアップ

Dockerイメージのビルド

docker-compose build

サービスの起動

docker-compose up

コーディング規約

Python

PEP 8に準拠したコードを書く
Blackを使用してコードをフォーマットする
isortを使用してインポートを整理する
Flake8を使用してコードをリントする
mypyを使用して型チェックを行う

命名規則

クラス名: CamelCase
関数名: snake_case
変数名: snake_case
定数名: UPPER_CASE
モジュール名: snake_case
パッケージ名: snake_case

ドキュメンテーション

すべての関数、クラス、メソッドにはDocstringを記述する
DocstringはGoogle Styleに準拠する

def calculate_centrality(G, centrality_type="degree", **kwargs):
    """
    中心性指標を計算します。
    
    Args:
        G: NetworkXグラフ
        centrality_type: 中心性タイプ
        **kwargs: 追加のパラメータ
        
    Returns:
        ノードIDをキー、中心性値を値とする辞書
        
    Raises:
        ValueError: 無効な中心性タイプが指定された場合
    """
    # 実装

JavaScript/TypeScript

Airbnb JavaScript Style Guideに準拠したコードを書く
ESLintを使用してコードをリントする
Prettierを使用してコードをフォーマットする

命名規則

コンポーネント名: PascalCase
関数名: camelCase
変数名: camelCase
定数名: UPPER_CASE
ファイル名: コンポーネントはPascalCase、それ以外はcamelCase

ドキュメンテーション

すべての関数、コンポーネント、クラスにはJSDocを記述する

/**
 * ネットワークデータを可視化します。
 * 
 * @param {Object} data - ネットワークデータ
 * @param {Array} data.nodes - ノードのリスト
 * @param {Array} data.links - リンクのリスト
 * @param {Object} options - 可視化オプション
 * @returns {Object} 可視化結果
 */
function visualizeNetwork(data, options) {
    // 実装
}

テスト方法

バックエンドのテスト

ユニットテスト

# APIのユニットテスト
cd API
pytest tests/unit

# NetworkXMCPのユニットテスト
cd ../NetworkXMCP
pytest tests/unit

統合テスト

# APIの統合テスト
cd API
pytest tests/integration

# NetworkXMCPの統合テスト
cd ../NetworkXMCP
pytest tests/integration

システムテスト

# システムテスト
cd ..
pytest test_system_integration.py

フロントエンドのテスト

cd frontend
npm test

テストカバレッジの確認

# APIのテストカバレッジ
cd API
pytest --cov=.

# NetworkXMCPのテストカバレッジ
cd ../NetworkXMCP
pytest --cov=.

# フロントエンドのテストカバレッジ
cd ../frontend
npm test -- --coverage

デプロイ方法

本番環境へのデプロイ

本番用の環境変数を設定

cp .env.example .env.prod

.env.prodファイルを編集して、本番環境用の環境変数を設定します。

本番用のDockerイメージをビルド

docker-compose -f docker-compose.prod.yml build

本番環境にデプロイ

docker-compose -f docker-compose.prod.yml up -d

CI/CDパイプライン

LLMGraphvisプロジェクトでは、GitHub Actionsを使用してCI/CDパイプラインを構築しています。

CI（継続的インテグレーション）

プルリクエストが作成されると、自動的にテストが実行されます
コードスタイルのチェックが行われます
テストカバレッジが計算されます

CD（継続的デリバリー）

mainブランチにマージされると、自動的にステージング環境にデプロイされます
リリースタグが作成されると、自動的に本番環境にデプロイされます

トラブルシューティング

よくあるエラーと解決策

データベース接続エラー

エラー:

sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) could not connect to server: Connection refused

解決策:

PostgreSQLサービスが起動しているか確認する
.envファイルのデータベース接続情報が正しいか確認する
ネットワーク設定を確認する

NetworkXMCP通信エラー

エラー:

MCPCommunicationError: Error from NetworkXMCP: Connection refused

解決策:

NetworkXMCPサービスが起動しているか確認する
.envファイルのNETWORKX_MCP_URLが正しいか確認する
ネットワーク設定を確認する

GraphML検証エラー

エラー:

GraphMLValidationError: Invalid GraphML content: Missing <graph> element

解決策:

GraphMLファイルの内容を確認する
GraphMLファイルが正しい形式か確認する
必要に応じて、GraphMLファイルを修正する

よくある質問

Q: 新しいレイアウトアルゴリズムを追加するにはどうすればよいですか？

A: 以下の手順で新しいレイアウトアルゴリズムを追加できます。

NetworkXMCP/layouts/layout_functions.pyに新しいレイアウト関数を追加する
get_layout_function関数に新しいレイアウトを登録する
必要に応じて、テストを追加する

Q: 新しい中心性指標を追加するにはどうすればよいですか？

A: 以下の手順で新しい中心性指標を追加できます。

NetworkXMCP/metrics/centrality_functions.pyに新しい中心性関数を追加する
get_centrality_function関数に新しい中心性を登録する
必要に応じて、テストを追加する

Q: 大規模グラフの処理でパフォーマンスの問題が発生した場合、どうすればよいですか？

A: 以下の対策を検討してください。

キャッシュを活用する
非同期処理を使用する
部分計算を行う
近似アルゴリズムを使用する
サーバーのリソースを増やす

Q: 新しいAPIエンドポイントを追加するにはどうすればよいですか？

A: 以下の手順で新しいAPIエンドポイントを追加できます。

必要に応じて、API/models/に新しいモデルを追加する
必要に応じて、API/schemas/に新しいスキーマを追加する
API/routers/に新しいルーターを追加する
必要に応じて、API/services/に新しいサービスを追加する
API/main.pyで新しいルーターを登録する
テストを追加する

Q: フロントエンドに新しい機能を追加するにはどうすればよいですか？

A: 以下の手順で新しい機能を追加できます。

必要に応じて、frontend/src/services/に新しいサービスを追加する
必要に応じて、frontend/src/components/に新しいコンポーネントを追加する
必要に応じて、frontend/src/pages/に新しいページを追加する
必要に応じて、frontend/src/App.jsxでルーティングを更新する
テストを追加する

貢献ガイドライン

プルリクエストのプロセス

新しい機能やバグ修正のためのブランチを作成する
コードを変更する
テストを追加または更新する
コードスタイルを確認する
プルリクエストを作成する
コードレビューを受ける
必要に応じて、コードを修正する
プルリクエストがマージされる

コミットメッセージの規約

コミットメッセージは、以下の形式に従ってください。

<type>(<scope>): <subject>

<body>

<footer>

type: コミットの種類（feat, fix, docs, style, refactor, test, chore）
scope: コミットの影響範囲（api, networkx_mcp, frontend, common）
subject: コミットの簡潔な説明
body: コミットの詳細な説明
footer: 関連するIssueやBreaking Changesの情報

例:

feat(api): ネットワークエクスポート機能の追加

- GraphMLエクスポート機能を追加
- エクスポート時のエラーハンドリングを改善

Closes #123

概要​

目次​

プロジェクト構造​

主要なモジュールの責務​

API​

NetworkXMCP​

common​

開発環境のセットアップ​

前提条件​

ローカル開発環境のセットアップ​

Docker環境のセットアップ​

コーディング規約​

Python​

命名規則​

ドキュメンテーション​

JavaScript/TypeScript​

命名規則​

ドキュメンテーション​

テスト方法​

バックエンドのテスト​

ユニットテスト​

統合テスト​

システムテスト​

フロントエンドのテスト​

テストカバレッジの確認​

デプロイ方法​

本番環境へのデプロイ​

CI/CDパイプライン​

CI（継続的インテグレーション）​

CD（継続的デリバリー）​

トラブルシューティング​

よくあるエラーと解決策​

データベース接続エラー​

NetworkXMCP通信エラー​

GraphML検証エラー​

よくある質問​

Q: 新しいレイアウトアルゴリズムを追加するにはどうすればよいですか？​

Q: 新しい中心性指標を追加するにはどうすればよいですか？​

Q: 大規模グラフの処理でパフォーマンスの問題が発生した場合、どうすればよいですか？​

Q: 新しいAPIエンドポイントを追加するにはどうすればよいですか？​

Q: フロントエンドに新しい機能を追加するにはどうすればよいですか？​

貢献ガイドライン​

プルリクエストのプロセス​

コミットメッセージの規約​

参考リンク​

概要

目次

プロジェクト構造

主要なモジュールの責務

API

NetworkXMCP

common

開発環境のセットアップ

前提条件

ローカル開発環境のセットアップ

Docker環境のセットアップ

コーディング規約

Python

命名規則

ドキュメンテーション

JavaScript/TypeScript

命名規則

ドキュメンテーション

テスト方法

バックエンドのテスト

ユニットテスト

統合テスト

システムテスト

フロントエンドのテスト

テストカバレッジの確認

デプロイ方法

本番環境へのデプロイ

CI/CDパイプライン

CI（継続的インテグレーション）

CD（継続的デリバリー）

トラブルシューティング

よくあるエラーと解決策

データベース接続エラー

NetworkXMCP通信エラー

GraphML検証エラー

よくある質問

Q: 新しいレイアウトアルゴリズムを追加するにはどうすればよいですか？

Q: 新しい中心性指標を追加するにはどうすればよいですか？

Q: 大規模グラフの処理でパフォーマンスの問題が発生した場合、どうすればよいですか？

Q: 新しいAPIエンドポイントを追加するにはどうすればよいですか？

Q: フロントエンドに新しい機能を追加するにはどうすればよいですか？

貢献ガイドライン

プルリクエストのプロセス

コミットメッセージの規約

参考リンク