Speckleのアーキテクチャ｜Project/Model/Versionと旧Stream/Branch/Commitの対応

この記事は Speckle の内部構造を整理します。Speckleとは を読んだ前提で、データがどんな階層で管理され、クライアントがどう認証して通信するかを見ていきます。データの中身（オブジェクト）の話は次の オブジェクトモデル で深掘りします。

1全体構成（Server とクライアント）

Speckle のアーキテクチャは、中心に Speckle Server があり、その周囲に各種クライアント（コネクタ、SDK、Web フロントエンド、Viewer）が接続する構成です。

2データの階層（Project / Model / Version / Object）

Speckle のデータは入れ子の階層で整理されます。

Object（オブジェクト） は、Version が指し示す実データです。ルートとなる Base オブジェクトから、子オブジェクトへとツリー状に広がります（オブジェクトモデル 参照）。関係を一言でいえば、「Project の中に複数の Model があり、各 Model は複数の Version を時系列に持ち、各 Version が 1 つのオブジェクトツリーを指す」という構造です。

3新旧用語の対応表（最重要）

Speckle は旧版（v2 系）と新世代で主要な用語が変わりました。古い資料や旧版の UI を見るときに混乱しやすいため、対応関係を必ず押さえてください。

このたとえはあくまで理解の補助です。Speckle の Model は Git のブランチほど厳密なマージ概念を持つわけではなく、「同じ Project 内でデータを目的別に分ける枝」という運用的な意味合いが中心です。古い資料を読むときは、まずこの対応表を手元に置き、Stream とあれば Project、Branch とあれば Model、Commit とあれば Version と頭の中で読み替えると、新旧どちらの記述でも迷わず追えるようになります。

4認証（アクセストークン）

クライアントがサーバにアクセスするには認証が必要です。基本は パーソナルアクセストークン（PAT） を使います。トークンには操作範囲を絞る「スコープ」を設定でき、たとえば読み取りのみ、ストリーム作成可、といった権限を付与できます。

コネクタや SDK は、ユーザのアカウントに紐づいたトークンを使ってサーバにアクセスします。自動化スクリプトでは、必要最小限のスコープのトークンを発行して使うのが安全です。

5GraphQL API

Speckle Server は GraphQL API を公開しています。REST のように URL ごとにエンドポイントが分かれるのではなく、単一のエンドポイントに対してクエリを投げ、必要なフィールドだけを取得・更新する方式です。

• Project / Model / Version の一覧取得や作成、メタデータの読み取りなどが API で行える。
• 大きなオブジェクトデータ本体は、GraphQL とは別の専用の転送経路（Transport の仕組み）でやり取りされる。
• SDK（specklepy など）は、内部でこの GraphQL API を呼び出して階層情報を操作している。

API の全体像は API概要 も参照してください。

6クライアントから見た流れ

まとめると、クライアントがデータを送るときは、次の順序になります。受け取るときは逆に、Version が指すオブジェクトツリーを取得して、各ツールのネイティブ要素へ復元します。

この流れを支えているのが、(1) 認証によるアクセス制御、(2) Project / Model / Version という階層、(3) 内容ハッシュで管理されるオブジェクトツリー、という 3 つの要素です。コネクタも SDK も Web フロントエンドも、見た目こそ違え、内部ではこの同じ仕組みの上で動いています。したがって、どのクライアントを使う場合でも「どの Project / Model に、どの Version として送るのか」を意識することが、Speckle を扱う上での共通の考え方になります。

この具体的な操作は send／receive の基本ワークフロー で扱います。データそのものの構造を理解するには、次の オブジェクトモデル に進んでください。

→次に読む