> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.
# アーキテクチャ
> BRICKS Buttress の構成 — コンポーネント、データフロー、ロードマップ
BRICKS Buttress はクライアント、サーバー、バックエンドコア、共有ハードウェアガードレールの 4 層に明確に分かれており、JSON-RPC WebSocket プロトコルと UDP 自動検出トランスポートで接続されます。下図は目標アーキテクチャです。[実装済みと計画中](#実装済みと計画中)セクションで、現在出荷されているものとロードマップ上のものを示します。
## 完全なアーキテクチャ
```mermaid theme={null}
%%{init: {'flowchart': {'curve': 'basis', 'padding': 12}}}%%
flowchart TB
subgraph Foundation["📱 BRICKS Foundation"]
direction LR
iOS["iOS App"]
Android["Android App"]
Desktop["Desktop"]
Web["Web App"]
end
subgraph Client["🔌 Buttress Client"]
direction LR
WS["WebSocket
+ JSON-RPC"]
Discovery["Autodiscovery
(UDP broadcast)"]
Auth["Workspace
JWT Auth"]
end
iOS & Android & Desktop & Web ==> Client
subgraph Servers["🖥️ Buttress Servers"]
direction LR
ServerLinux["Buttress Server
Linux / GPU"]
ServerMac["Buttress Server
macOS"]
ServerDocker["Buttress Server
Docker"]
end
Client ==> ServerLinux & ServerMac & ServerDocker
subgraph Backend["⚙️ Buttress Backend"]
direction LR
WSServer["WebSocket Server
(JSON-RPC 2.0)"]
Session["Session
Management"]
Announcer["Autodiscovery
Announcer"]
Queue["Queue
Management"]
end
Servers ==> Backend
subgraph Core["🧠 Backend Core"]
direction LR
Registry["Generator Registry
(ref counting)"]
LLM["GGML LLM"]
STT["GGML STT"]
Printer["Thermal Printer"]
Future["Future Backends"]
end
Backend ==> Core
subgraph Guardrails["🛡️ Hardware Guardrails
(shared client + server)"]
direction LR
Capability["Capability
Detection"]
Memory["Memory Estimation
(KV cache, model fit)"]
Scoring["Performance
Scoring"]
end
Core -. shared .-> Guardrails
Client -. shared .-> Guardrails
classDef foundation fill:#3b82f6,stroke:#1d4ed8,stroke-width:1.5px,color:#ffffff
classDef client fill:#d97706,stroke:#92400e,stroke-width:1.5px,color:#ffffff
classDef server fill:#ea580c,stroke:#9a3412,stroke-width:2px,color:#ffffff
classDef backend fill:#d97706,stroke:#92400e,stroke-width:1.5px,color:#ffffff
classDef core fill:#c2410c,stroke:#7c2d12,stroke-width:1.5px,color:#ffffff
classDef guardrails fill:#10b981,stroke:#047857,stroke-width:1.5px,color:#ffffff
classDef planned fill:#94a3b833,stroke:#94a3b8,stroke-width:1px,stroke-dasharray:5 4,color:#64748b
class iOS,Android,Desktop,Web foundation
class WS,Discovery,Auth client
class ServerLinux,ServerMac,ServerDocker server
class WSServer,Session,Announcer,Queue backend
class Registry,LLM,STT core
class Capability,Memory,Scoring guardrails
class Printer,Future planned
style Foundation fill:#3b82f61a,stroke:#3b82f6,stroke-width:1.5px,color:#3b82f6
style Client fill:#d977061a,stroke:#d97706,stroke-width:1.5px,color:#d97706
style Servers fill:#ea580c2e,stroke:#ea580c,stroke-width:2px,color:#ea580c
style Backend fill:#d977061a,stroke:#d97706,stroke-width:1.5px,color:#d97706
style Core fill:#c2410c1a,stroke:#c2410c,stroke-width:1.5px,color:#c2410c
style Guardrails fill:#10b9811a,stroke:#10b981,stroke-width:1.5px,color:#10b981
linkStyle default stroke:#d97706,stroke-width:2px
```
オレンジの実線矢印は実行時のデータパスを表します。緑の点線矢印は **Hardware Guardrails** パッケージがクライアントとサーバー両側で共有されている場所を示し、双方で同じコードが動作します。グレーの破線ノード（Thermal Printer、Future Backends）はロードマップ上の未リリース項目です。
## 各層の役割
| 層 | 役割 |
| ------------------- | ---------------------------------------------------------- |
| Buttress Server | 全機能を統合した完全版サーバー — WebSocket RPC、自動検出、ファイル転送 |
| Buttress Backend | 自動検出を含まないバックエンド（組み込み用途） |
| Autodiscovery | UDP ブロードキャストおよび HTTP エンドポイント検出 |
| Buttress Client | Foundation デバイスがサーバーに接続するために使うクライアントライブラリ |
| Backend Core | generator 実装（LLM、STT、MLX、将来のサーマルプリンター） |
| Hardware Guardrails | 共有の能力検出・スコアリングロジック — クライアントとサーバーが同じコードを実行するため、同一基準で自己採点できる |
## 能力比較の仕組み
Foundation デバイスが generator を起動すると、クライアントとサーバーがハードウェア情報を交換し、どちら側で実行するかを決めます：
1. **クライアントがローカルの能力を収集。** GPU/CPU 情報、利用可能メモリ、モデルメタデータ（層数、embedding サイズ、KV cache 要件）。
2. **クライアントが能力情報をサーバーに送信。** モデル識別子と要求コンテキストサイズも一緒に送ります。
3. **サーバーが両側を評価。** クライアントが報告した能力とサーバー自身に対して同じ guardrails コードを実行し、双方に 0〜100 のパフォーマンススコアとメモリ収まり判定を返します。
4. **サーバーが推奨を返却** — `local`、`buttress`、`either` のいずれか。
5. **クライアントが決定。** 自身のストラテジー（`prefer-local`、`prefer-buttress`、`prefer-best`）と推奨結果から最終的に選びます。詳細は [Foundation から Buttress を使用](/ja/foundation/buttress#ストラテジー)を参照してください。
クライアントとサーバーが同じ guardrails パッケージを共有しているため、スコアは直接比較可能です — 双方間に較正のずれは生じません。
## 実装済みと計画中
### 実装済み
* **ワークスペース JWT 認証** — ワークスペースごとに Ed25519 発行者、短命な `{ k:'ba', w_id, … }` access token。[ワークスペースバインディング](/ja/buttress/workspace-binding)を参照。
* **UDP 自動検出と署名付きアナウンス** — UDP `8089` 上の `ANNOUNCE`／`QUERY`／`RESPONSE`、アナウンスにバックエンドごとのハードウェア能力を含めます。バインド済みサーバーは登録済みの Ed25519 アナウンス鍵で全パケットに署名し、launcher は 30 秒のリプレイウィンドウで署名を検証します。プロトコルバージョンは `2.0`。[LAN 自動検出](/ja/buttress/autodiscovery)を参照。
* **参照カウント方式の generator registry** — 複数クライアントで読み込み済みモデルを共有でき、refcount が 0 になるとサーバーが自動クリーンアップ。
* **GGML LLM、MLX LLM、GGML STT バックエンド。**
* **能力検出とスコアリング** — 双方で同じ guardrails コードを実行。
* **STT のファイル転送** — デバイスが `POST /buttress/upload` に音声をアップロード。
### 計画中
* **キュー管理** — 優先度サポート付きのハードウェア対応リクエストキュー。
* **Docker 配布** — CUDA／Vulkan サポート付きのプリビルドイメージ。
* **複数サーバープール選択** — 同一ワークスペースに複数のバインド済みサーバーがある場合の能力ベースのランキング（現在は最終視認者が勝ち）。
* **サーマルプリンターバックエンド** — LLM／STT 以外のオフロードターゲット。
## 関連項目
JWT 認証がアーキテクチャにどう収まるか。
UDP トランスポート、アナウンスペイロード、能力スコアリング。