コアコンセプト

Quantickleは、ドキュメントセット全体を結びつける少数の共有概念に基づいています。

• 座標系と空間レイアウト — Quantickleの絶対レイアウトおよび深度対応レイアウトは、x、y、z座標に0～1000の立方体を使用します。完全な空間ルールと照明動作についてはCOORDINATE_SYSTEM.mdを参照してください。

• グラフファイル管理とプロジェクトファイル — .qutファイルは正規の保存状態であり、ノード、エッジ、メタデータ、コンテナ階層を保存します。

• Neo4j連携 — サーバーはメタデータスナップショットを含むグラフをNeo4jに永続化および取得できます。設定とワークフローの詳細はNEO4J_INTEGRATION_README.mdを参照してください。

データモデル

Quantickleのグラフは、レイアウト、スタイリング、グループ化を駆動するメタデータを持つノードとエッジの集合です。

• グラフ: メタデータ、ノード配列、エッジ配列、およびオプションのレイアウトまたはビューステートを含む完全なデータセット。
• ノード: 必須のidと、label、type、size、color、座標などのオプション属性を持つ頂点。ノードにはMarkdownのinfoや連携で使用されるカスタムプロパティを含めることもできます。
• エッジ: source + targetノードIDと、オプションのlabel、type、weight、スタイリングメタデータを持つ関係。
• コンテナ: 関連要素をグループ化するノード。コンテナはネスト可能で、視覚的または意味的な境界として機能することがよくあります。

Quantickleの内部グラフJSONは、nodesとedges配列を持つフラットな構造です。コンテナの関係とクラスはノードメタデータとして保持されます。

インポート・エクスポート形式

Quantickleは、ファイル→データインポートおよび自動化された連携から、いくつかのインポート形式を受け入れます。各インポーターは、.qutプロジェクトファイルを保存するときに使用されるのと同じグラフパイプラインにデータを供給するため、以下の構造はエクスポートの形状も表しています。

CSVインポート

CSVインポーターは2つのレイアウトを認識します。

1. ノード＋エッジセクション – Quantickleが使用するエクスポート形式であり、手動でデータを準備する場合に最も安全なオプションです。ファイルにはノードテーブルに続いて空の行とエッジテーブルが含まれます: ```csv node_id,node_label,node_type,node_size,node_color,node_x,node_y srv-1,Gateway,server,40,#2dd4bf,100,250 cli-1,Analyst,client,28,#38bdf8,320,210

   source,target,label,weight,type srv-1,cli-1,allows,1,connection

   root@kitploit:~

追加の列は許容されます—インポーターはNode Label、nodeLabel、labelなどのヘッダーを正規化し、明示的なcolor/size値を保持し、座標が指定されている場合はそれを維持します。

2. オプション属性を持つエッジリスト – 少なくともsourceとtargetカラムを含む最小限のCSV。label、type、weight、source_type、target_type、source_label、colorなどのオプションのカラムは、存在する場合、生成されたノードとエッジにマージされます： ```csv source,target,label,source_type,target_type srv-1,cli-1,allows,server,client srv-1,sensor-2,monitors,server,sensor
   root@kitploit:~

Quantickleはヘッダーを大文字小文字を区別せずに解析し、snake_caseとスペース区切りの名前の両方を受け入れ、空の行を自動的にスキップします。

Edge list (.edges)

プレーンな空白区切りのエッジペアが、簡単なスケルトングラフのためにサポートされています。欠落したノードは自動的に作成されます:```text srv-1 cli-1 srv-1 sensor-2

> **注記:** Excelワークブック（`.xlsx`）はサポートされなくなりました。Quantickleにインポートする前に、データをCSVとしてエクスポートまたは保存してください。

#### JSON

`File → Import Data` は、Quantickleが生成したJSONエクスポートや、生のCytoscape要素コレクションも受け入れます。ファイルに`elements`と入れ子の`data`エントリが含まれている場合、それらはQuantickleの内部構造に正規化されます。

#### Quantickleグラフ（`.qut`）

`.qut`ファイルは、フラット化されたノードとエッジオブジェクトを持つJSONドキュメントです。最小限のグラフは次のようになります：```json
{
  "metadata": { "name": "My graph" },
  "nodes": [
    { "id": "srv-1", "label": "Gateway", "type": "server", "size": 40 }
  ],
  "edges": [
    { "id": "srv-1_cli-1", "source": "srv-1", "target": "cli-1", "label": "allows" }
  ]
}

Legacy files that store nodes/edges inside a data object are still accepted—the loader flattens them automatically and preserves coordinates, classes, and container hierarchy metadata.

API payloads

When exchanging data with the HTTP API or Neo4j integration, send the same flattened shape used by .qut files:```json { "nodes": [ { "id": "srv-1", "label": "Gateway", "type": "server", "size": 40 } ], "edges": [ { "id": "srv-1_cli-1", "source": "srv-1", "target": "cli-1", "label": "allows" } ] }

The optional `info` field still supports Markdown and is persisted alongside any
custom properties.

<a id="layouts"></a>
## レイアウト

Quantickle はレイアウトを実用的なファミリーにグループ化し、タスクに適したものを選択できます:

- **力指向** (force, cose, fcose) — 探索的な構造の発見や自然なクラスタリングを求める場合に適しています。
- **階層的・フロー** (breadthfirst, dagre) — 依存関係ツリー、コールグラフ、因果フローに最適です。
- **グリッド＆サークル** — ダッシュボード、小規模グラフ、エクスポート向けの高速で決定論的なレイアウト。
- **時間ベース** (timeline, timeline-scatter, temporal-attraction) — 時間的な順序や最近性が重要な場合に使用します。
- **空間的/絶対** (absolute, depth-aware) — 既知の座標を持つ地図状または図式的なレイアウトに使用します。
- **クラスタ/放射状** (radial-recency) — タイプ別のグループ化や最近性のリングを求める場合に使用します。

### レイアウトオプション```javascript
// js/layouts.js
const layoutOptions = {
  'force': {
    name: 'force',
    animate: true,
    randomize: false,
    infinite: false
  },
  'grid': {
    name: 'grid',
    rows: undefined,
    cols: undefined
  }
  // ... more layouts
}

タイムラインのレイアウト

カスタムtimelineレイアウトは、ノードを時間軸に沿って配置します。barStyleオプションを使用して中央のバーをカスタマイズできます。```javascript cy.layout({ name: 'timeline', barStyle: { color: '#3498db', // bar color height: 15, // bar height in pixels className: 'my-timeline-bar' // optional CSS class } }).run();

When `className` が指定されると、タイムラインバーにそのクラスが適用され、デフォルトの色と高さのスタイルが削除されるため、CSSで直接スタイリングできます。

### Radial Recency Layout

`radial-recency` を使用すると、最新のアイテムを中心に最も近くにプロットし、古いものは外側のリングに配置します。このレイアウトは角度を二次属性（タイプ/クラスター/グループ）にマッピングし、関連するノードが円周に沿って整列されるようにします。リングは以下のオプションで調整できます:```javascript
cy.layout({
  name: 'radial-recency',
  ringThickness: 140, // radial spacing between time rings
  minSeparation: 80,  // minimum distance between neighbors along a ring
  angleJitter: 0.15,  // optional jitter (radians) to break perfect symmetry
  angleStrategy: 'grouped' // or 'alphabetical' for deterministic ordering
}).run();

graphs/radial_time_rings.qut を参照してください。これは、クラスター/タイプメタデータによってグループ化された同心円状の時間帯を示す小さなフィクスチャです。

タイムライン散布図レイアウト

timeline-scatter レイアウトを使用すると、タイムスタンプを x 位置に直接マッピングし、ノードを類似性、カテゴリ、またはコミュニティによって垂直方向に分散させることができます。両軸に調整可能なスケールと、オーバーラップを減らすためのオプションのジッターを受け入れます:```javascript cy.layout({ name: 'timeline-scatter', xScale: 0.5, // pixels per millisecond (auto-calculated when omitted) yScale: 60, // spread for similarity/category lanes jitter: 4, // optional per-node jitter to minimise overlap barStyle: { // applied when timeline bars already exist color: '#222', height: 12, className: 'scatter-bar' } }).run();

Nodes with numeric similarity scores (`similarity`, `similarityScore`, or `similarity_score`) are centred around the mean, while categorical or community labels create evenly spaced lanes along the y-axis.

### Temporal Attraction Layout

Use timestamp distance to steer spring strengths while keeping repulsion light:```javascript
cy.layout({
  name: 'temporal-attraction',
  timeMode: 'gaussian',          // or 'bucket'
  timeSigma: 60 * 60 * 1000,     // Gaussian falloff window (in ms)
  bucketSize: 24 * 60 * 60 * 1000, // bucket size when using bucket mode
  repulsionStrength: 12          // minimal node repulsion
}).run();

Select Layout → Temporal Attraction - Time Weighted in the UI or pass name: 'temporal-attraction' through the CLI/API layout configuration to enable it.

インテグレーション

Quantickleは外部システムからデータを取得したり、同期したりできます。インテグレーションは通常、資格情報、プロキシルール、永続性が必要なため、サーバーを介して行われます。

• Neo4j — グラフスナップショットの保存とクエリを行います。NEO4J_INTEGRATION_README.mdを参照してください。
• SerpAPI — RAGパイプラインでウェブ検索に使用されます。APIキーを参照してください。
• VirusTotal — ドメイン/IP/ファイル/URLインテリジェンスとリレーションシップグラフでノードを強化します。
• CIRCL-LU (MISP OSINTフィード) — CIRCL-LUフィードから厳選されたMISPイベントを取り込みます。
• OPML RSSウォッチャー — OPMLフィードリストをインポートし、一致する記事をグラフに変換します。

ワークフロー

🧭 アプリの最初のステップ

• ブラウザでhttp://localhost:3000にアクセスしてUIを起動します。
• ファイル → ワークスペースを設定を使用して、プロジェクトファイルの保存場所を選択します。
• ファイル → データをインポートからデータセットをインポートするか、クリップボードからデータを貼り付けるか、またはコンテキストメニューを使用して手動でノードを配置します。
• 必要に応じて、グラフ、型定義、データテーブルビューを切り替えます。
• 詳細な編集にはツール → ノードエディターからノードエディターを開きます。
• グラフのデフォルト値を設定するには、ツール → グラフエリアエディターを使用します。

詳細なチュートリアルやスクリーンショットについては、使用ガイドを参照してください。

エクスポートと共有

• .qutに保存すると、レイアウト、メタデータ、コンテナを含む完全なプロジェクトスナップショットが作成されます。
• CSVをエクスポートすると、スプレッドシートツールやグラフパイプラインとの相互運用が可能です。
• 静的HTML、PNG、またはPDFをエクスポートして、レポートにすぐに使用できる出力を得られます。

初期化

Quantickleは、js/main.jsで定義されたグローバルwindow.QuantickleAppを通じて初期化されます。DOMの準備が整うと、アプリケーションは自動的にwindow.QuantickleApp.init()を呼び出します。

設定

パフォーマンス設定```javascript

// js/config.js const config = { performance: { nodeLimit: 1000, // Max nodes to render at once batchSize: 100, // Nodes to add per batch webgl: true, // Enable WebGL rendering hideEdgesOnViewport: false // Hide edges while dragging } }

<a id="api"></a>
## API

### HTTP API

Expressサーバー（`server.js`）は静的フロントエンドを提供し、UIで使用されるいくつかのJSONエンドポイントを公開します。すべてのルートは`/api`で始まります：

| メソッドとパス | 説明 |
| --- | --- |
| `GET /api/domain-files` | `assets/domains/`にあるJSONドメイン定義を一覧表示します。 |
| `GET /api/examples` | バンドルされたサンプル`.qut`グラフのメタデータを返します。 |
| `GET /api/serpapi` | Google検索リクエストをSerpApiにプロキシします。クエリ文字列または環境に`SERPAPI_API_KEY`が必要です。 |
| `GET /api/openai/models` | OpenAIモデルリストリクエストを`api.openai.com`にプロキシします。`Authorization: Bearer ...`ヘッダーが必要です。 |
| `GET /api/proxy?url=…` | HTTP/HTTPSリクエストをブラウザ風ヘッダーで許可されたホストに転送します。 |
| `POST /api/neo4j/graph` | グラフをNeo4jに永続化します。上記で説明した平坦化されたQuantickleグラフJSONボディを受け付けます。 |
| `POST /api/neo4j/node-graphs` | 提供された`labels`配列に一致するノードを含む保存済みグラフを検索します。 |
| `GET /api/neo4j/graphs` | Neo4jに保存されたグラフを要約メタデータとともに一覧表示します。 |
| `GET /api/neo4j/graph/:name` | 保存されたグラフを取得し、`metadata`、`nodes`、`edges`を返します。 |
| `DELETE /api/neo4j/graph/:name` | 保存されたグラフをNeo4jから削除します。 |

すべてのNeo4jエンドポイントは、`X-Neo4j-Url`、`X-Neo4j-Username`、`X-Neo4j-Password`ヘッダー（またはサーバー上の`NEO4J_URL`、`NEO4J_USER`、`NEO4J_PASSWORD`環境変数）を介して認証情報を受け付けます。提供された場合、`metadata`オブジェクトはグラフと一緒に保存され、`savedAt`タイムスタンプが自動的に追加されます。

<a id="api-keys"></a>
### API Keys

一部の機能にはAPIキーが必要です。これらはIntegrationsパネルを介してブラウザのローカルストレージに保存されます。

- **SerpAPI** — RAGパイプラインのWeb検索に必要です。Integrationsダイアログでキーを追加すると、クライアントサイドのRAGパイプラインで使用されます。
- **VirusTotal** — ドメイン/IP/ファイル/URLノードを強化し、関係グラフを取得するために使用されます。
- **CIRCL-LU** — MISPフィードで必要な場合のオプションの認証情報。

コマンドラインで使用する場合は、代わりに環境変数`SERPAPI_API_KEY`を設定してもかまいません。

<a id="backend-proxy"></a>
### Backend Proxy

サーバーは、プロキシ許可リストに含まれるホストにHTTP(S)リクエストを転送するCORS回避プロキシを公開します。URLパラメータ付きで`/api/proxy`を使用します：```
curl "http://localhost:3000/api/proxy?url=https%3A%2F%2Fopentip.kaspersky.com%2F"

基本の許可リストは config/proxy-allowlist.json にあります。このファイルを提供するか、サーバーを起動する前にカンマ区切りの環境変数 PROXY_ALLOWLIST を設定する必要があります。そうしないと、プロキシは致命的な設定エラーをログに記録し、すべてのリクエストを HTTP 403 で拒否します。

統合固有のホスト（OpenAI や VirusTotal などのバックエンド統合アダプタ用）は config/integration-allowlist.json（または INTEGRATION_ALLOWLIST）で管理されます。実行時には、両方の許可リストがマージされます。各エントリは、プロキシが接続を許可するホストまたはワイルドカードパターンをリストする必要があります。* を使用したワイルドカードはエントリ内の任意の場所でサポートされているため、*.example.com は example.com のすべてのサブドメインを許可し、news-* のようなマスクも期待通りに動作します。サブドメインは親ドメインのエントリも継承するため、example.com を追加すると自動的に www.example.com が許可されます。

最小限の許可リストファイルは次のようになります：

``````json
{
  "allowlist": ["otx.alienvault.com", "feeds.example.org"]
}

環境変数を使用したい場合は、サーバーを起動する前に PROXY_ALLOWLIST="otx.alienvault.com,feeds.example.org" を設定してください。

プロキシがリクエストを転送する際、ブラウザライクなヘッダーセット（最新のChromeの User-Agent、Accept、Accept-Language、Sec-Fetch-* 値を含む）を送信するようになりました。これにより、アンチボットフィルターの背後でコンテンツをゲートしているサイトも、通常のページ読み込みと同じように応答します。これらのヘッダーは、必要に応じてクライアントリクエストから x-proxy-<header> 上書きを指定することでオーバーライドできます。

ストレージ

Quantickleは、作業中のグラフ状態をブラウザに保持し、エクスポートまたは同期時に永続化します。

• ブラウザストレージ — 設定とAPIキーはブラウザ内にローカルに保存されます。
• プロジェクトファイル (.qut) — 忠実度の高いグラフスナップショットとしてワークスペースフォルダに保存されます。ワークスペースのルールとファイルライフサイクルについては GRAPH_FILE_MANAGEMENT_README.md を参照してください。
• Neo4j — オプションのサーバーサイド永続化で、コラボレーションと検索に対応します。Neo4j統合を介して設定します。

プロジェクト構造```

quantickle/ ├── assets/ # Static assets │ ├── backgrounds/ # Background graphics │ ├── icons/ # Mostly empty now; icons are colocated with node types │ ├── domains/ # Node type definitions │ ├── help/ # Help pages │ ├── examples/ # Example graphs │ └── css/ # Stylesheets referenced by index.html ├── config/ # Proxy allowlist ├── data_retrieval/ # SerpAPI/web search helpers used by the RAG pipeline ├── graphs/ # Workspace folder for bundled and test .qut graphs ├── js/ # Front-end source modules │ ├── main.js # Application bootstrap │ ├── ai-input-manager.js # Currently unused │ ├── api.js # HTTP client for server endpoints │ ├── graph.js # Graph rendering and management │ ├── graph-manager.js # High-level graph state orchestration │ ├── graph-reference-resolver.js # Normalization of graph references │ ├── layouts.js # Layout registration and options │ ├── 3d-globe-layout.js # 3D Layout │ ├── absolute-layout.js # Absolute coordinate layout │ ├── custom-layouts.js # Other custom layouts │ ├── aggressive-performance-fix.js # Aggressive Performance Fix for Large Graph Panning │ ├── non-invasive-performance-fix.js # Non-Invasive Performance Fix for Large Graphs │ ├── lod-system.js # Level of Detail (LOD) System │ ├── auto-refresh.js # Auto-refresh functionality when new data arrives │ ├── config.js # Default settings │ ├── domain-loader.js # Loading and managing domain-specific node type configurations │ ├── edge-editor.js # Editing edge styles │ ├── extensions.js # Loading and registration of Cytoscape extensions │ ├── integrations.js # Configuration and connection to external services │ ├── rag-pipeline.js # Handles AI-assisted data ingestion │ ├── secure-storage.js # Encrypts sensitive values in sessionStorage │ ├── source-editor.js # Editor for the JSON graph source │ ├── tables.js # Data table updates, filtering, and display │ ├── ui.js # User interface interactions and notifications │ ├── validation.js # Validation of all data inputs │ ├── workspace-manager.js # Workspace file functionality │ ├── utils.js # Shared browser utilities │ ├── integrations/ # Integration-specific helpers (MISP/CIRCL-LU, etc.) │ └── features/ # Feature modules (node editor, callouts, timeline, ...) ├── tests/ # Automated regression tests covering UI flows, imports, and APIs ├── utils/ # Node helpers (Neo4j client, readability shim, CLI scripts) ├── public/ │ ├── index.html # Static front-end │ └── favicon.ico # Main app icon ├── package.json # Node dependencies and scripts └── server.js # Express server exposing the HTTP API

<a id="troubleshooting"></a>
## 🐛 トラブルシューティング

### よくある問題

1. **グラフが描画されない**
   - ブラウザのコンソールでエラーを確認する
   - データ形式を確認する
   - WebGLのサポートを確認する

2. **パフォーマンスが低い**
   - 設定でノード制限を減らす
   - WebGLレンダリングを有効にする
   - 大きなグラフにはシンプルなレイアウトを使用する

3. **レイアウトの問題**
   - 別のレイアウトアルゴリズムを試す
   - レイアウトパラメータを調整する
   - 接続されていないノードを確認する

## 🤝 コントリビューション

このプロジェクトは正規のリポジトリとして積極的にメンテナンスされていません。プルリクエストはおそらく無視されます。ただし、フィードバック、バグ報告、コメントは歓迎します。

## 📄 ライセンス

このプロジェクトはApache 2.0ライセンスの下でライセンスされています。詳細はLICENSEファイルを参照してください。

## 🙏 謝辞

- [Cytoscape.js](https://js.cytoscape.org/) を使用して構築
- さまざまなCytoscapeコントリビューターによるレイアウトアルゴリズム
- 大規模グラフ可視化研究に触発されたパフォーマンス最適化

<a id="additional-documentation"></a>
## 📚 追加ドキュメント

- [使用方法ガイド](https://github.com/rsac-labs/quantickle/blob/HEAD/USAGE_GUIDE.md)
- [グラフファイル管理](https://github.com/rsac-labs/quantickle/blob/HEAD/GRAPH_FILE_MANAGEMENT_README.md)
- [Neo4j統合](https://github.com/rsac-labs/quantickle/blob/HEAD/NEO4J_INTEGRATION_README.md)
- [座標系](https://github.com/rsac-labs/quantickle/blob/HEAD/COORDINATE_SYSTEM.md)
- [パフォーマンスガイド](https://github.com/rsac-labs/quantickle/blob/HEAD/PERFORMANCE.md)