Core concepts
This section builds the mental model behind Nodus. If Getting started showed you how to run a cluster, this section explains what the pieces are and why they behave as they do — so the API stops being a set of methods and becomes a coherent picture.
Everything in Nodus hangs off a single running handle, INodusNode. The concepts below map one-to-one to the capability areas on that handle.
The one handle, six areas
A product holds one INodusNode, and each capability is a first-class area on it. There is no "advanced" tier and no triple-hop to reach a capability. You get the handle once, from the entry point, and everything is reachable from it.
Each area is a thin facade over the core services, so the same running node exposes membership, leadership, messaging, events, health, and gossip without any further wiring.
How a cluster is put together
A Nodus cluster is a peer-to-peer mesh. There is no central coordinator process: every member holds a direct TCP connection to every other member, heartbeats flow continuously between them, and exactly one member holds leadership for the current epoch.
Every node runs the same engine. There is no "server" role that is special infrastructure — the leader is simply a member the cluster has agreed to designate, and any member can become leader on failover.
The five concepts
The five concepts below each answer one question and map to one node area. Read them in order, starting with membership.
| Concept | The question it answers | Node area | Read |
|---|---|---|---|
| Membership | Who is in the cluster right now, and how do they join and leave? | node.Cluster | Membership |
| Leader election | Which single member coordinates, and what happens when it fails? | node.Leadership | Leader election |
| Messaging | How does one node address another, send it work, and get a reply? | node.Messaging | Messaging |
| Cluster events | How does one node announce something to everyone at once? | node.Events | Cluster events |
| Health and gossip | How do nodes tell "slow" from "gone", and share state cheaply? | node.Health, node.Gossip | Health and gossip |
How the concepts reinforce each other
The areas are not independent — they are layered on the same connections:
- Membership is maintained by the health subsystem: a node becomes a member when it handshakes in, and leaves membership when heartbeats stop and the suspicion window elapses.
- Leader election runs over membership: an election considers the reachable members, and every membership change (a join or a leave) can trigger a fresh election.
- Messaging and cluster events ride the same pipelined-TCP transport the heartbeats do — direct messaging for one-to-one traffic, the event bus for one-to-many.
- Gossip rides on the heartbeat traffic itself, so a product can piggyback its own state summary without opening a second protocol.
Start with Membership — it is the ground the other concepts stand on.
Next steps
- Membership — who is in the cluster, and how join and leave work.
- Leader election — how the cluster agrees on one coordinator.
- Building a node — how you obtain the
INodusNodehandle in the first place.