Key concepts
The handful of ideas behind Folkways in plain words — workspaces, segments, topics, events, identities, tokens and cursors.
The big picture
┌──────────────┐ 1. "give me a token" ┌──────────────┐
│ Your app │ ──────────────────────► │ Your backend │ signs it with the
│ (SDK client) │ ◄────────────────────── │ │ segment's signing key
└──────┬───────┘ token └──────┬───────┘
│ 2. connect with the token │ (optional) publish over HTTP
▼ ▼
┌──────────────────────────────────────────────────────┐
│ Folkways node (your segment) │
│ topics: chat/lobby rides/42/location typing/lobby │
└──────────────────────────────────────────────────────┘
▲ 3. publish / subscribe
│
other users' appsYour app never holds a secret. Your backend vouches for each user by signing a short-lived token, the node checks it, and from then on the app publishes and subscribes to topics directly.
Glossary
| Term | In one line |
|---|---|
| Workspace | Your team's account: members, plan and billing |
| Segment | One realtime app, fully isolated from every other |
| Node | The Folkways server your apps connect to |
| Topic | A named channel, such as chat/lobby, that events are published to |
| Event | One message on a topic: a name, some data and a delivery type |
| Delivery type | How the node keeps an event: stream, kv or signal |
| Identity | Who is connected, such as user:42, as your backend said |
| Token | A short-lived pass that names an identity and its permissions |
| Signing key | The key pair your backend signs tokens with |
| Publishable key | A public key for read-only, anonymous apps |
| Session | One live connection and what the node confirmed about it |
| Cursor | A position in a topic's history, used to resume |
Workspace
Your organisation in the dashboard. It holds your team members and their roles, your plan, and your segments.
Segment
One realtime app, for example "Chat (production)". Everything in Folkways is scoped to a segment: topics, signing
keys, publishable keys, limits and usage. Two segments never see each other's data, even with the same topic
names. Create one segment per app and environment, such as chat-staging and chat-production.
A segment has an ID (a UUID). Your backend puts it in every token, so the node knows which app a user belongs to. Your app never sends it.
Node
The Folkways realtime server. Your app connects to the node URL shown on the segment's Connect tab. The SDK
derives the WebSocket address (wss://…/v1/ws) and the HTTP addresses from it.
Topic
A named channel. Anyone with permission can publish events to it and subscribe to its events. Topic names are
paths, such as chat/lobby, rides/42/location or scores/match-7.
You don't create topics: a topic exists as soon as someone uses it, if a topic rule in the dashboard allows its name. More in Topics and events.
Event
One thing that happened on a topic. Every event has:
- a name you choose, such as
message,typingorlocation; - data: any JSON value, a string or bytes;
- a delivery type (see below);
- a publisher: the identity that sent it, filled in by the node. Trust it; never trust a name inside the data.
Delivery type
How the node keeps and delivers an event:
| Type | Think of it as | Good for |
|---|---|---|
stream | An ordered log you can replay | Chat messages, activity feeds, orders |
kv | A shared key-value map; only the latest value per key counts | Locations, read receipts, status, scores |
signal | A short-lived "I'm doing this now", gone after 5 seconds | Typing indicators, live cursors |
The dashboard calls these Durable, Last value and Ephemeral. Details and examples in Topics and events.
Identity
Who a connection acts for, such as user:42 or driver:7. Your backend chooses the format and puts it in the
token; the node stamps it on every event as the publisher. One identity can be connected from several devices or
tabs at once.
A connection with no identity is anonymous. Anonymous connections can only read.
Token
A short-lived, signed pass (a JWT) that says which segment, which identity and which permissions. Tokens live up to 15 minutes; the SDK asks your backend for a new one before the old one expires. See How authentication works.
Signing key
A key pair registered on a segment. Your backend keeps the private half and signs tokens with it; the node keeps
only the public half and checks signatures. A key has an ID (kid) so you can rotate keys without downtime.
Publishable key
A key that starts with rte_pk_ and may be shipped inside a web page or mobile app. It can only read, and it never
names a user: the SDK trades it for an anonymous, read-only token. Use it for public live pages without a backend.
See Publishable keys.
Session
What client.connect() returns: the identity the node confirmed, the segment, your permissions, the token's
expiry and the node's limits. A new session starts on every reconnect; the SDK keeps your subscriptions across
them.
Cursor
A position in a topic's stream, written "epoch:seq". The SDK remembers the cursor of the last event you handled
on each topic and, after a reconnect, resumes right after it, so you miss nothing and see nothing twice.