タイトル: アーキテクチャ（Server/Project/Model/Version）
SEOタイトル: Speckleのアーキテクチャ｜Project/Model/Versionと旧Stream/Branch/Commitの対応
アーキテクチャ — Server と Project/Model/Version
中心の Speckle Server に、コネクタや SDK、Web フロントエンドが接続する構成。データは Project → Model → Version という入れ子の階層で管理されます。新旧用語の対応表とあわせて全体像をつかみましょう。
この記事の要点
- Speckle は Server を中心に、Project → Model → Version という階層でデータを管理する
- 新旧用語は対応している：Project＝旧 Stream、Model＝旧 Branch、Version＝旧 Commit
- 実データはバージョンに紐づくオブジェクトツリー（Base オブジェクト群）として保存される
- クライアントはアクセストークンで認証し、GraphQL API 経由でサーバとやり取りする
- コネクタや SDK は、この API を通じてオブジェクトを送受信している
この記事は Speckle の内部構造を整理します。Speckleとは を読んだ前提で、データがどんな階層で管理され、クライアントがどう認証して通信するかを見ていきます。データの中身（オブジェクト）の話は次の オブジェクトモデル で深掘りします。
1全体構成（Server とクライアント）
Speckle のアーキテクチャは、中心に Speckle Server があり、その周囲に各種クライアント（コネクタ、SDK、Web フロントエンド、Viewer）が接続する構成です。
- データの保存先であり、GraphQL API を公開する中核
- 商用クラウドとして提供されるほか、自前でも構築できる（ホスティング）
2データの階層（Project / Model / Version / Object）
Speckle のデータは入れ子の階層で整理されます。
Object（オブジェクト） は、Version が指し示す実データです。ルートとなる Base オブジェクトから、子オブジェクトへとツリー状に広がります（オブジェクトモデル 参照）。関係を一言でいえば、「Project の中に複数の Model があり、各 Model は複数の Version を時系列に持ち、各 Version が 1 つのオブジェクトツリーを指す」という構造です。
3新旧用語の対応表（最重要）
Speckle は旧版（v2 系）と新世代で主要な用語が変わりました。古い資料や旧版の UI を見るときに混乱しやすいため、対応関係を必ず押さえてください。
| 新世代 | 旧版（v2） | 役割 | Git でのたとえ |
|---|---|---|---|
| Project | Stream | データの最上位の入れ物・共有単位 | リポジトリ |
| Model | Branch | 分野・用途ごとの枝分かれの単位 | ブランチ |
| Version | Commit | send ごとに作られるスナップショット | コミット |
| Object | Object | 実データ（変わらず Object） | ツリー／ブロブ |
このたとえはあくまで理解の補助です。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 の基本ワークフロー で扱います。データそのものの構造を理解するには、次の オブジェクトモデル に進んでください。