> ## 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 清楚地分為四層 — 客戶端、伺服器、後端核心，以及共用的硬體 guardrails — 透過 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<br/>+ JSON-RPC"]
        Discovery["Autodiscovery<br/>(UDP broadcast)"]
        Auth["Workspace<br/>JWT Auth"]
    end

    iOS & Android & Desktop & Web ==> Client

    subgraph Servers["🖥️ Buttress Servers"]
        direction LR
        ServerLinux["Buttress Server<br/>Linux / GPU"]
        ServerMac["Buttress Server<br/>macOS"]
        ServerDocker["Buttress Server<br/>Docker"]
    end

    Client ==> ServerLinux & ServerMac & ServerDocker

    subgraph Backend["⚙️ Buttress Backend"]
        direction LR
        WSServer["WebSocket Server<br/>(JSON-RPC 2.0)"]
        Session["Session<br/>Management"]
        Announcer["Autodiscovery<br/>Announcer"]
        Queue["Queue<br/>Management"]
    end

    Servers ==> Backend

    subgraph Core["🧠 Backend Core"]
        direction LR
        Registry["Generator Registry<br/>(ref counting)"]
        LLM["GGML LLM"]
        STT["GGML STT"]
        Printer["Thermal Printer"]
        Future["Future Backends"]
    end

    Backend ==> Core

    subgraph Guardrails["🛡️ Hardware Guardrails<br/><span style='font-weight:400;font-size:0.85em'>(shared client + server)</span>"]
        direction LR
        Capability["Capability<br/>Detection"]
        Memory["Memory Estimation<br/>(KV cache, model fit)"]
        Scoring["Performance<br/>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
```

<Tip>
  橘色實線箭頭代表執行階段的資料路徑。綠色虛線箭頭表示 **Hardware Guardrails** 套件在客戶端與伺服器兩側共用 — 雙方執行同一份程式碼。灰色虛線節點（Thermal Printer、Future Backends）為路線圖上尚未推出的項目。
</Tip>

## 各層職責

| 層                   | 角色                                      |
| ------------------- | --------------------------------------- |
| 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 資訊、可用記憶體、模型 metadata（層數、embedding 大小、KV cache 需求）。
2. **客戶端將能力資訊送至伺服器**，並附帶模型識別子與要求的 context 長度。
3. **伺服器同時評估雙方** — 將相同的 guardrails 程式碼套用於客戶端回報的能力與伺服器自身。雙方各取得 0-100 的效能評分與記憶體適配判定。
4. **伺服器回傳建議** — `local`、`buttress` 或 `either`。
5. **客戶端據此決定**，依其策略（`prefer-local`、`prefer-buttress`、`prefer-best`）與建議結果做最終選擇。詳見[從 Foundation 使用 Buttress](/zh-Hant/foundation/buttress#策略)。

由於客戶端與伺服器共用同一個 guardrails 套件，雙方分數可直接比較 — 不會有校準偏差。

## 已實作與計劃中

### 已實作

* **工作區 JWT 認證** — 每個工作區擁有 Ed25519 核發者，短期 `{ k:'ba', w_id, … }` access token。請參閱[工作區繫結](/zh-Hant/buttress/workspace-binding)。
* **UDP 自動探索與簽署過的通告** — UDP `8089` 上的 `ANNOUNCE`／`QUERY`／`RESPONSE`，通告中夾帶各後端的硬體能力。每台已繫結伺服器以登錄的 Ed25519 通告金鑰簽署所有封包，launcher 驗證簽章並套用 30 秒重放視窗。協定版本為 `2.0`。請參閱[區域網路自動探索](/zh-Hant/buttress/autodiscovery)。
* **參考計數的 generator registry** — 多個客戶端可共用同一已載入模型，refcount 歸零時伺服器自動清理。
* **佇列管理** — 針對 STT 的硬體感知請求排隊，平行 slot 狀態可於 [`/status` 儀表板](/zh-Hant/buttress/installation#確認運作)檢視。
* **GGML LLM、MLX LLM 與 GGML STT 後端。**
* **能力偵測與評分** — 雙方執行相同的 guardrails 程式碼。
* **STT 檔案傳輸** — 裝置上傳音訊至 `POST /buttress/upload`。

### 計劃中

* **Docker 發行** — 預建好支援 CUDA／Vulkan 的映像檔。
* **多伺服器池選擇** — 同一工作區存在多台已繫結伺服器時的能力感知排序（目前以最近見到者為準）。
* **熱感印表機後端** — LLM／STT 之外的額外卸載目標。

## 相關文件

<CardGroup cols={2}>
  <Card title="工作區繫結" icon="key" href="/zh-Hant/buttress/workspace-binding">
    JWT 認證如何融入此架構。
  </Card>

  <Card title="區域網路自動探索" icon="broadcast-tower" href="/zh-Hant/buttress/autodiscovery">
    UDP 傳輸、通告酬載與能力評分。
  </Card>
</CardGroup>