# skeptik-io/herald architecture

> Architecture diagram of the GitHub repository skeptik-io/herald, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skeptik-io/herald
- Repository: https://github.com/skeptik-io/herald

## Overview

Herald is a multi-tenant realtime event transport: backends provision streams and members through HTTP, while clients connect over WebSocket to subscribe, publish, receive acknowledgments, and catch up after reconnects. Its Rust server supplies the transport and optional chat and presence engines; TypeScript SDKs provide browser, chat-state, and React interfaces, alongside generated multi-language admin clients. The graph preserves documented chat and presence capabilities, but their internal server routing is not fully represented because those source excerpts were not sampled.

Main entry points: [`herald-sdk-typescript/src/client.ts`](https://github.com/skeptik-io/herald/blob/main/herald-sdk-typescript/src/client.ts) (WebSocket SDK), [`herald-server/src/ws/handler.rs`](https://github.com/skeptik-io/herald/blob/main/herald-server/src/ws/handler.rs) (WebSocket protocol handler), [`herald-server/src/engine.rs`](https://github.com/skeptik-io/herald/blob/main/herald-server/src/engine.rs) (Engine extension system), [`herald-chat-core/src/chat-core.ts`](https://github.com/skeptik-io/herald/blob/main/herald-chat-core/src/chat-core.ts) (Chat state machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Herald Server"]
  node_server_main["Server startup<br/>[main.rs]"]
  node_engine_set["Engine extension system<br/>[engine.rs]"]
  node_ws_handler["WebSocket protocol handler<br/>[handler.rs]"]
  node_ws_connection["Connection lifecycle<br/>[connection.rs]"]
  node_http_api["HTTP API routes"]
  node_event_store[("Event buffer<br/>[events.rs]")]
  node_member_store[("Stream membership<br/>[members.rs]")]
  node_cursor_store[("Read cursors<br/>[cursors.rs]")]
end

subgraph group_features["Domain Engines"]
  node_chat_engine["Chat features"]
  node_presence_engine["Presence features"]
end

subgraph group_clients["Client SDKs"]
  node_sdk["WebSocket SDK<br/>[client.ts]"]
  node_sdk_connection["Reconnect transport<br/>[connection.ts]"]
  node_sdk_e2ee["E2EE manager<br/>[e2ee.ts]"]
  node_chat_core["Chat state machine<br/>[chat-core.ts]"]
  node_react_ui["React chat UI<br/>[provider.tsx]"]
  node_chat_sdk["Chat protocol SDK<br/>[client.ts]"]
  node_presence_sdk["Presence protocol SDK<br/>[client.ts]"]
end

subgraph group_admin["Backend Administration"]
  node_admin_sdk["Admin SDK<br/>[client.ts]"]
  node_admin_transport["Admin HTTP transport<br/>[transport.ts]"]
  node_admin_langs["Other language clients<br/>[client.py]"]
end

node_browser(("Browser client"))
node_backend(("Application backend"))

node_backend -->|"manages through"| node_admin_sdk
node_admin_sdk -->|"sends requests"| node_admin_transport
node_admin_transport -->|"calls HTTP"| node_http_api
node_browser -->|"uses"| node_sdk
node_sdk -->|"creates connection"| node_sdk_connection
node_sdk -->|"encrypts events"| node_sdk_e2ee
node_sdk -->|"exchanges frames"| node_ws_handler
node_ws_handler -->|"reads and writes"| node_event_store
node_ws_handler -->|"checks membership"| node_member_store
node_ws_handler -->|"reads cursor"| node_cursor_store
node_server_main -->|"registers engines"| node_engine_set
node_engine_set -->|"dispatches hooks"| node_chat_engine
node_engine_set -->|"dispatches hooks"| node_presence_engine
node_chat_sdk -->|"extends frames"| node_sdk
node_presence_sdk -->|"extends frames"| node_sdk
node_chat_core -->|"uses transport"| node_sdk
node_react_ui -->|"provides UI for"| node_chat_core
node_backend -.->|"may use"| node_admin_langs

click node_server_main "https://github.com/skeptik-io/herald/blob/main/herald-server/src/main.rs"
click node_engine_set "https://github.com/skeptik-io/herald/blob/main/herald-server/src/engine.rs"
click node_ws_handler "https://github.com/skeptik-io/herald/blob/main/herald-server/src/ws/handler.rs"
click node_ws_connection "https://github.com/skeptik-io/herald/blob/main/herald-server/src/ws/connection.rs"
click node_http_api "https://github.com/skeptik-io/herald/tree/main/herald-server/src/http"
click node_event_store "https://github.com/skeptik-io/herald/blob/main/herald-server/src/store/events.rs"
click node_member_store "https://github.com/skeptik-io/herald/blob/main/herald-server/src/store/members.rs"
click node_cursor_store "https://github.com/skeptik-io/herald/blob/main/herald-server/src/store/cursors.rs"
click node_chat_engine "https://github.com/skeptik-io/herald/tree/main/herald-server/src/engines/chat"
click node_presence_engine "https://github.com/skeptik-io/herald/tree/main/herald-server/src/engines/presence"
click node_sdk "https://github.com/skeptik-io/herald/blob/main/herald-sdk-typescript/src/client.ts"
click node_sdk_connection "https://github.com/skeptik-io/herald/blob/main/herald-sdk-typescript/src/connection.ts"
click node_sdk_e2ee "https://github.com/skeptik-io/herald/blob/main/herald-sdk-typescript/src/e2ee.ts"
click node_chat_core "https://github.com/skeptik-io/herald/blob/main/herald-chat-core/src/chat-core.ts"
click node_react_ui "https://github.com/skeptik-io/herald/blob/main/herald-chat-react/src/provider.tsx"
click node_chat_sdk "https://github.com/skeptik-io/herald/blob/main/herald-chat-sdk-typescript/src/client.ts"
click node_presence_sdk "https://github.com/skeptik-io/herald/blob/main/herald-presence-sdk-typescript/src/client.ts"
click node_admin_sdk "https://github.com/skeptik-io/herald/blob/main/herald-admin-typescript/src/client.ts"
click node_admin_transport "https://github.com/skeptik-io/herald/blob/main/herald-admin-typescript/src/transport.ts"
click node_admin_langs "https://github.com/skeptik-io/herald/blob/main/herald-admin-python/herald_admin/client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_main,node_engine_set,node_ws_handler,node_ws_connection,node_http_api,node_event_store,node_member_store,node_cursor_store,node_browser toneBlue
class node_chat_engine,node_presence_engine toneAmber
class node_sdk,node_sdk_connection,node_sdk_e2ee,node_chat_core,node_react_ui,node_chat_sdk,node_presence_sdk toneMint
class node_admin_sdk,node_admin_transport,node_admin_langs toneRose
class node_backend toneIndigo
```

## Components

### Herald Server

- [Server startup](https://github.com/skeptik-io/herald/blob/main/herald-server/src/main.rs): `herald-server/src/main.rs`
- [Engine extension system](https://github.com/skeptik-io/herald/blob/main/herald-server/src/engine.rs): `herald-server/src/engine.rs`
- [WebSocket protocol handler](https://github.com/skeptik-io/herald/blob/main/herald-server/src/ws/handler.rs): `herald-server/src/ws/handler.rs`
- [Connection lifecycle](https://github.com/skeptik-io/herald/blob/main/herald-server/src/ws/connection.rs): `herald-server/src/ws/connection.rs`
- [HTTP API routes](https://github.com/skeptik-io/herald/tree/main/herald-server/src/http): `herald-server/src/http`
- [Event buffer](https://github.com/skeptik-io/herald/blob/main/herald-server/src/store/events.rs): `herald-server/src/store/events.rs`
- [Stream membership](https://github.com/skeptik-io/herald/blob/main/herald-server/src/store/members.rs): `herald-server/src/store/members.rs`
- [Read cursors](https://github.com/skeptik-io/herald/blob/main/herald-server/src/store/cursors.rs): `herald-server/src/store/cursors.rs`

### Domain Engines

- [Chat features](https://github.com/skeptik-io/herald/tree/main/herald-server/src/engines/chat): `herald-server/src/engines/chat`
- [Presence features](https://github.com/skeptik-io/herald/tree/main/herald-server/src/engines/presence): `herald-server/src/engines/presence`

### Client SDKs

- [WebSocket SDK](https://github.com/skeptik-io/herald/blob/main/herald-sdk-typescript/src/client.ts): `herald-sdk-typescript/src/client.ts`
- [Reconnect transport](https://github.com/skeptik-io/herald/blob/main/herald-sdk-typescript/src/connection.ts): `herald-sdk-typescript/src/connection.ts`
- [E2EE manager](https://github.com/skeptik-io/herald/blob/main/herald-sdk-typescript/src/e2ee.ts): `herald-sdk-typescript/src/e2ee.ts`
- [Chat state machine](https://github.com/skeptik-io/herald/blob/main/herald-chat-core/src/chat-core.ts): `herald-chat-core/src/chat-core.ts`
- [React chat UI](https://github.com/skeptik-io/herald/blob/main/herald-chat-react/src/provider.tsx): `herald-chat-react/src/provider.tsx`
- [Chat protocol SDK](https://github.com/skeptik-io/herald/blob/main/herald-chat-sdk-typescript/src/client.ts): `herald-chat-sdk-typescript/src/client.ts`
- [Presence protocol SDK](https://github.com/skeptik-io/herald/blob/main/herald-presence-sdk-typescript/src/client.ts): `herald-presence-sdk-typescript/src/client.ts`

### Backend Administration

- [Admin SDK](https://github.com/skeptik-io/herald/blob/main/herald-admin-typescript/src/client.ts): `herald-admin-typescript/src/client.ts`
- [Admin HTTP transport](https://github.com/skeptik-io/herald/blob/main/herald-admin-typescript/src/transport.ts): `herald-admin-typescript/src/transport.ts`
- [Other language clients](https://github.com/skeptik-io/herald/blob/main/herald-admin-python/herald_admin/client.py): `herald-admin-python/herald_admin/client.py`

### Other components

- **Browser client**
- **Application backend**

## Connections

- Application backend → Admin SDK: manages through
- Admin SDK → Admin HTTP transport: sends requests
- Admin HTTP transport → HTTP API routes: calls HTTP
- Browser client → WebSocket SDK: uses
- WebSocket SDK → Reconnect transport: creates connection
- WebSocket SDK → E2EE manager: encrypts events
- WebSocket SDK → WebSocket protocol handler: exchanges frames
- WebSocket protocol handler → Event buffer: reads and writes
- WebSocket protocol handler → Stream membership: checks membership
- WebSocket protocol handler → Read cursors: reads cursor
- Server startup → Engine extension system: registers engines
- Engine extension system → Chat features: dispatches hooks
- Engine extension system → Presence features: dispatches hooks
- Chat protocol SDK → WebSocket SDK: extends frames
- Presence protocol SDK → WebSocket SDK: extends frames
- Chat state machine → WebSocket SDK: uses transport
- React chat UI → Chat state machine: provides UI for
- Application backend → Other language clients: may use