タイトル: アーキテクチャ（Server/Project/Model/Version）
SEOタイトル: Speckleのアーキテクチャ｜Project/Model/Versionと旧Stream/Branch/Commitの対応
| この記事の要点 |
|
この記事は Speckle の内部構造を整理します。Speckleとは を読んだ前提で、データがどんな階層で管理され、クライアントがどう認証して通信するかを見ていきます。データの中身（オブジェクト）の話は次の オブジェクトモデル で深掘りします。
全体構成（Server とクライアント）
Speckle のアーキテクチャは、中心に Speckle Server があり、その周囲に各種クライアント（コネクタ、SDK、Web フロントエンド、Viewer）が接続する構成です。
- Server：データの保存先であり、GraphQL API を公開する中核。商用クラウドとして提供されるほか、自前でも構築できます（ホスティング）。
- クライアント：Revit などの コネクタ、specklepy や .NET SDK、Web アプリ、Viewer など。いずれもサーバの API を介してデータを送受信します。
データの階層（Project / Model / Version / Object）
Speckle のデータは入れ子の階層で整理されます。
- Project（プロジェクト）：データの最上位の入れ物。1つの案件やワークスペースに相当します。権限管理や共有の単位でもあります。
- Model（モデル）：Project の中で、用途や分野ごとにデータを枝分かれさせる単位。たとえば「意匠」「構造」「設備」のように分けられます。
- Version（バージョン）：Model に対して send するたびに作られる、ある時点のスナップショット。これがバージョン履歴になります。
- Object（オブジェクト）：Version が指し示す実データ。ルートとなる Base オブジェクトから、子オブジェクトへとツリー状に広がります（オブジェクトモデル 参照）。
関係を一言でいえば、「Project の中に複数の Model があり、各 Model は複数の Version を時系列に持ち、各 Version が1つのオブジェクトツリーを指す」という構造です。
新旧用語の対応表（最重要）
Speckle は旧版（v2 系）と新世代で主要な用語が変わりました。古い資料や旧版の UI を見るときに混乱しやすいため、対応関係を必ず押さえてください。
| 新世代 | 旧版（v2） | 役割 | Git でのたとえ |
|---|---|---|---|
| Project | Stream | データの最上位の入れ物・共有単位 | リポジトリ |
| Model | Branch | 分野・用途ごとの枝分かれの単位 | ブランチ |
| Version | Commit | send ごとに作られるスナップショット | コミット |
| Object | Object | 実データ（変わらず Object） | ツリー／ブロブ |
このたとえはあくまで理解の補助です。Speckle の Model は Git のブランチほど厳密なマージ概念を持つわけではなく、「同じ Project 内でデータを目的別に分ける枝」という運用的な意味合いが中心です。
認証（アクセストークン）
クライアントがサーバにアクセスするには認証が必要です。基本は パーソナルアクセストークン（PAT） を使います。トークンには操作範囲を絞る「スコープ」を設定でき、たとえば読み取りのみ、ストリーム作成可、といった権限を付与できます。
- コネクタや SDK は、ユーザのアカウントに紐づいたトークンを使ってサーバにアクセスします。
- 自動化スクリプトでは、必要最小限のスコープのトークンを発行して使うのが安全です。
- トークンは秘密情報なので、ソースコードに直書きせず環境変数などで管理します。
GraphQL API
Speckle Server は GraphQL API を公開しています。REST のように URL ごとにエンドポイントが分かれるのではなく、単一のエンドポイントに対してクエリを投げ、必要なフィールドだけを取得・更新する方式です。
- Project / Model / Version の一覧取得や作成、メタデータの読み取りなどが API で行えます。
- 大きなオブジェクトデータ本体は、GraphQL とは別の専用の転送経路（後述の Transport の仕組み）でやり取りされます。
- SDK（specklepy など）は、内部でこの GraphQL API を呼び出して階層情報を操作しています。
API の全体像は API概要 も参照してください。
クライアントから見た流れ
まとめると、クライアントがデータを送るときは、(1) トークンで認証し、(2) 対象の Project / Model を特定し、(3) オブジェクトツリーをサーバに転送し、(4) その内容を指す新しい Version を作成する、という順序になります。受け取るときは逆に、Version が指すオブジェクトツリーを取得して、各ツールのネイティブ要素へ復元します。この具体的な操作は send／receive の基本ワークフロー で扱います。データそのものの構造を理解するには、次の オブジェクトモデル に進んでください。