suaveplan/docs/network/README.md

Network

The network layer is the resilient, tiered, plugin-driven mesh that lets every drive in a deployment talk to every other drive — and keeps them talking when the central server goes away.

The user's framing: "a resilient tiered network system where if the server goes down, it's all in place with meshed pockets of users with their nominated hosts / those hosts on a tier nominate their tier host."

That is what this layer is. The canonical capability spec is the largest spec in the monorepo: openspec/specs/network/spec.md — 125 numbered requirements (NET-01..NET-125) covering plugins, transports, sessions, governance, partitions, relay, content delivery, and four hosting models.

Documents in this folder

File	Purpose
architecture.md	NetworkNode, NetworkPlugin, NetworkBus, MessageEnvelope, Transport, MessageRouter. The plugin substrate that everything else lives on.
topology-and-failover.md	The tier model (Tier 0 / 1 / 2), meshed pockets, host election, graceful degradation when the server disconnects, and how server reintegration reconciles. The four hosting models (PURE_CLIENT, SERVER_BASED, SERVER_TO_CLIENT_FAILOVER, CLIENT_WITH_SERVER_BACKUP).
plugins-catalog.md	Every network plugin and what it does — protocol, registry, governance, failover, topology, transport-manager, webrtc, content-delivery, audit-mesh, relay, assignment, partition, circuit-breaker, qos, migration, auth, server-bridge, session, simulation, monitor, middleware.
security-and-tokens.md	Ed25519 message signatures, server-signed mesh/session/capability tokens, peer identity challenge-response, plugin security verifier, tier-specific policies, cross-mesh trust validators.
offline-and-reintegration.md	What the mesh does without the server — token grace periods, signed log buffering, reconciliation on reconnect, log compaction.
implementation-status.md	What's shipped, pending, and the network-suite-wide cleanup needed before all 21 plugins compose cleanly.

One-paragraph summary

NetworkNode is the single entry-point: it owns a NetworkBus for typed pub/sub, a MessageRouter for envelope delivery, a transport pool, and a plugin chain. Every feature the network provides is a plugin; the core does plugin lifecycle (install → start → stop → dispose) and message routing, nothing else. Plugins talk to each other only via bus topics — no direct imports — so any plugin can be replaced or removed without touching the others. The result is a network that scales from a single in-process node (using MemoryTransport) to a worldwide tiered mesh (using WebRTC/WebSocket/HTTPS transports with relay, partition handling, circuit breakers, and a server bridge). Every message is signed with the sender's Ed25519 key. Every host election produces a server-attested capability token. Every cross-mesh hop is loop-detected and TTL-bounded. When the server vanishes, the mesh keeps running on signed tokens with grace-period extensions and buffers signed log entries until it returns.

The bet

The bet is that plugin composition beats monolithic protocol. Instead of one giant network library that does everything, the genesis design has 21 small plugins each owning exactly one concern, talking only through NetworkBus. Add network-plugin-relay and you can hop across meshes; remove it and you can't. Add network-plugin-content-delivery and you have P2P chunks; remove it and you're a control-plane-only mesh. This is what makes the same NetworkNode work as a phone-to-phone WebRTC pair, a server-anchored corporate mesh, or a worldwide tiered overlay.

Reading order

1. architecture.md — the plugin substrate.
2. topology-and-failover.md — tiers, meshed pockets, server failover. Start here for resilience questions.
3. plugins-catalog.md — what each plugin does.
4. security-and-tokens.md — the trust model.
5. offline-and-reintegration.md — autonomous-mesh mode.
6. ../drive-storage-network.md — the whole composition.