diff --git a/README.md b/README.md index c3ae3a72..1a56875b 100644 --- a/README.md +++ b/README.md @@ -19,53 +19,9 @@ Turnstone gives LLMs tools — shell, files, search, web, planning — and orche - **Cluster dashboard** — real-time view of all nodes and workstreams, workstream creation with node targeting, reverse proxy for server UIs (only the console port needs network access) - **Cluster simulator** — test the stack at scale (up to 1000 nodes) without an LLM backend -```mermaid -graph LR - subgraph Clients - CLI[turnstone CLI] - UI[Browser UI] - SDK[SDK / API] - Discord[Discord / Slack] - end - - Console[turnstone-console
dashboard + proxy] - Channel[turnstone-channel
platform gateway] - - subgraph Cluster - Redis[(Redis MQ)] - DB[(PostgreSQL / SQLite)] - - subgraph Node A - BridgeA[bridge] - ServerA[server] - end - subgraph Node B - BridgeB[bridge] - ServerB[server] - end - end - - LLM[LLM Provider
OpenAI · Anthropic · local] - - CLI --> ServerA - UI --> ServerB - SDK --> Redis - Discord --> Channel - - Channel <--> Redis - Console --> Redis - Redis --> BridgeA & BridgeB - BridgeA --> ServerA - BridgeB --> ServerB - ServerA & ServerB --> LLM - - ServerA & ServerB --> DB - Console --> DB - Channel --> DB - ServerA -.->|notify| Channel - BridgeA & BridgeB -.->|events| Redis - Console -.->|proxy| ServerA & ServerB -``` +

+ Turnstone system architecture — data flow from clients through gateways, Redis MQ, cluster nodes, to LLM providers +

## Quickstart diff --git a/docs/diagrams/architecture-overview.svg b/docs/diagrams/architecture-overview.svg new file mode 100644 index 00000000..9f10216c --- /dev/null +++ b/docs/diagrams/architecture-overview.svg @@ -0,0 +1,286 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TURNSTONE + SYSTEM ARCHITECTURE + + + CLIENTS + GATEWAYS + MESSAGE QUEUE + CLUSTER NODES + LLM PROVIDERS + + + + + + + + + CLI + terminal REPL + + + + + + + + + Browser UI + HTTP + SSE + + + + + + + + + SDK / API + programmatic + + + + + + + + + Discord / Slack + chat platforms + + + + + + + + + + Console + dashboard + proxy + cluster management + + + + + + + + + Channel Gateway + platform adapter + Discord, Slack, ... + + + + + + + + + Redis MQ + + inbound queues + event pub/sub + node heartbeats + workstream routing + cluster state + + + + + + CLUSTER + + + + + + + + Node A + + + + bridge + + + server + + + + 14 tools + MCP + + + + + + + + + Node B + + + + bridge + + + server + + + + 14 tools + MCP + + + + + + + + + + OpenAI + GPT-5, o-series + + + + + + + + + Anthropic + Claude 4.5 / 4.6 + + + + + + + + + Local / vLLM + llama.cpp, NIM + + + + + + + + + PostgreSQL / SQLite + conversations, memory, auth + + STORAGE + + + + + + + + + + + + direct + + + + + + + + + + + + + + + + + + + proxy + + + + + + + + + + + + + + + + + + ... + + + + + events + + + + + interactive (direct) + + + + queue-driven + + + + proxy / events + + + + + + ROUTING + + target_node set → route to specific node queue + + ws_id set → route to owning node + + neither → shared queue, any node picks up \ No newline at end of file