> ## 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.
# Architecture
> How BRICKS Buttress fits together — components, data flow, and roadmap
BRICKS Buttress splits cleanly into four layers — clients, servers, backend cores, and shared hardware guardrails — connected by a JSON-RPC WebSocket protocol and a UDP autodiscovery transport. The diagram below is the target architecture; the [Implemented vs planned](#implemented-vs-planned) section calls out what ships today and what's still on the roadmap.
## Complete architecture
```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
```
Solid orange arrows are runtime data paths. Dashed green arrows mark where the **Hardware Guardrails** package is reused on both sides — the same code runs on the client and server. Dashed gray nodes (Thermal Printer, Future Backends) are on the roadmap but not yet shipped.
## Layer responsibilities
| Layer | Role |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Buttress Server | Combined server with all features — WebSocket RPC, autodiscovery, file transfer |
| Buttress Backend | Backend without autodiscovery (for embedded use) |
| Autodiscovery | UDP broadcast and HTTP endpoint discovery |
| Buttress Client | Client library used by Foundation devices to connect to servers |
| Backend Core | Generator implementations (LLM, STT, MLX, future thermal printer) |
| Hardware Guardrails | Shared capability detection and scoring logic — the same code runs on both client and server so they grade themselves on the same scale |
## How capability comparison works
When a Foundation device starts a generator, the client and server exchange hardware information so the system can pick the right side to run on:
1. **Client collects local capabilities.** GPU/CPU info, available memory, model metadata (layers, embedding size, KV cache requirements).
2. **Client sends capabilities to the server** along with the model identifier and requested context size.
3. **Server evaluates both sides** by running the same guardrails code on the client's reported caps and on its own. Each side gets a 0-100 performance score and a memory-fit verdict.
4. **Server returns a recommendation** — `local`, `buttress`, or `either`.
5. **Client decides** based on its strategy (`prefer-local`, `prefer-buttress`, `prefer-best`) and the recommendation. See [Use Buttress from Foundation](/foundation/buttress#strategies).
Because client and server share the guardrails package, the scores are directly comparable — there is no calibration drift between sides.
## Implemented vs planned
### Implemented
* **Workspace JWT authentication** — Ed25519 issuer per workspace, short-lived `{ k:'ba', w_id, … }` access tokens. See [Workspace binding](/buttress/workspace-binding).
* **UDP autodiscovery with signed announcements** — `ANNOUNCE`/`QUERY`/`RESPONSE` on UDP `8089`, with per-backend hardware caps in the announcement. Each bound server signs every packet with its registered Ed25519 announce key; launchers verify the signature with a 30-second replay window. Protocol version is `2.0`. See [LAN auto-discovery](/buttress/autodiscovery).
* **Generator registry with reference counting** — multiple clients can share a loaded model, and the server cleans up automatically when refcount hits zero.
* **Queue management** — hardware-aware request queuing for STT, with parallel-slot tracking visible on the [`/status` dashboard](/buttress/installation#verify).
* **GGML LLM, MLX LLM, and GGML STT backends.**
* **Capability detection and scoring** — same guardrails code on both sides.
* **File transfer for STT** — devices upload audio to `POST /buttress/upload`.
### Planned
* **Docker distribution** — pre-built images with CUDA / Vulkan support.
* **Multi-server pool selection** — caps-aware ranking when multiple bound servers are present in the same workspace (currently last-seen wins).
* **Thermal printer backend** — additional offload target beyond LLM/STT.
## Related
How JWT auth fits into the architecture.
The UDP transport, announcement payload, and capability scoring.