diff --git a/architecture.md b/architecture.md index 0823301..b7acdea 100644 --- a/architecture.md +++ b/architecture.md @@ -320,6 +320,7 @@ Payload fields: | Field | Type | Purpose | |---|---|---| | `protocol_version` | u8 | Wire format version | +| `site_id` | u16 | Site this node belongs to (`0` = local / unassigned) | | `tcp_port` | u16 | Port where this node accepts transport connections | | `function_flags` | u16 | Bitfield declaring node capabilities (see below) | | `name_len` | u8 | Length of name string | @@ -350,6 +351,32 @@ The system does not link against, depend on, or interact with Avahi or Bonjour. --- +## Multi-Site (Forward Compatibility) + +The immediate use case is a single LAN. A planned future use case is **site-to-site linking** — two independent networks (e.g. a lab and a remote location) connected by a tunnel (SSH port-forward, WireGuard, etc.), where nodes on both sites are reachable from either side. + +### Site Identity + +Every node carries a `site_id` (`u16`) in its announcement. In a single-site deployment this is always `0`. When sites are joined, each site is assigned a distinct non-zero ID; nodes retain their IDs across the join and are fully addressable by `(site_id, name)` from anywhere in the combined network. + +This field is reserved from day one so that multi-site never requires a wire format change or a rename of existing identifiers. + +### Site Gateway Node + +A site gateway is a node that participates in both networks simultaneously — it has a connection on the local transport and a connection over the inter-site tunnel. It: + +- Bridges discovery announcements between sites (rewriting `site_id` appropriately) +- Forwards encapsulated transport frames across the tunnel on behalf of cross-site edges +- Is itself a named node, so the control plane can see and reason about it + +The tunnel transport is out of scope for now. The gateway is a node type, not a special infrastructure component — it uses the same wire protocol as everything else. + +### Addressing + +A fully-qualified node address is `site_id:namespace:instance`. Within a single site, `site_id` is implicit and can be omitted. The control plane and discovery layer must store `site_id` alongside every peer record from the start, even if it is always `0`, so that the upgrade to multi-site addressing requires only configuration and a gateway node — not code changes. + +--- + ## Open Questions - What is the graph's representation format — in-memory object graph, serialized config, or both?