From 73129f16d7498d2575a261fde6c0ccb007e1c61b Mon Sep 17 00:00:00 2001 From: Johnathan Corgan Date: Fri, 13 Feb 2026 15:03:06 +0000 Subject: [PATCH] Rename design docs for clarity, reorganize node architecture diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - fips-architecture.md → fips-software-architecture.md with all cross-references updated (4 files) - fips-transport-abstraction.svg → fips-node-architecture.svg, moved from Transport Abstraction section to Architecture Overview in fips-intro.md - Added descriptive paragraph for node architecture diagram covering three-layer design (application interfaces, router core, transports) --- docs/design/README.md | 12 ++++++------ docs/design/fips-intro.md | 16 +++++++++++++--- ...bstraction.svg => fips-node-architecture.svg} | 0 ...itecture.md => fips-software-architecture.md} | 0 docs/design/fips-transports.md | 6 +++--- docs/design/fips-wire-protocol.md | 2 +- 6 files changed, 23 insertions(+), 13 deletions(-) rename docs/design/{fips-transport-abstraction.svg => fips-node-architecture.svg} (100%) rename docs/design/{fips-architecture.md => fips-software-architecture.md} (100%) diff --git a/docs/design/README.md b/docs/design/README.md index e5df8c4..8c09960 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -36,11 +36,11 @@ concepts, and finally the wire-level protocol details. ## Implementation -| Document | Description | -|--------------------------------------------------|------------------------------------------------------------------| -| [fips-architecture.md](fips-architecture.md) | Software architecture: entities, state machines, configuration | -| [fips-tun-driver.md](fips-tun-driver.md) | TUN interface driver: reader/writer threads, ICMPv6, packet flow | -| [fips-state-machines.md](fips-state-machines.md) | Phase-based state machine pattern: peer lifecycle, transitions | +| Document | Description | +|------------------------------------------------------------------|------------------------------------------------------------------| +| [fips-software-architecture.md](fips-software-architecture.md) | Software architecture: entities, state machines, configuration | +| [fips-tun-driver.md](fips-tun-driver.md) | TUN interface driver: reader/writer threads, ICMPv6, packet flow | +| [fips-state-machines.md](fips-state-machines.md) | Phase-based state machine pattern: peer lifecycle, transitions | ## Document Cross-References @@ -49,7 +49,7 @@ concepts, and finally the wire-level protocol details. │ ┌────────────┴────────────┐ ▼ ▼ - fips-session-protocol.md fips-architecture.md + fips-session-protocol.md fips-software-architecture.md │ │ ┌─────────┴─────────┐ ▼ ▼ ▼ fips-transports.md diff --git a/docs/design/fips-intro.md b/docs/design/fips-intro.md index 233d49d..f1c09c8 100644 --- a/docs/design/fips-intro.md +++ b/docs/design/fips-intro.md @@ -79,6 +79,18 @@ encryption transparently in either case. See [fips-transports.md](fips-transports.md) for transport options and characteristics. +![Node Architecture](fips-node-architecture.svg) + +Internally, each node is organized in three layers. At the top, two application +interfaces provide access to the mesh: a native datagram API addressed by npub, +and an IPv6 TUN adapter that maps npubs to `fd::/8` addresses so unmodified +IP applications can use the network transparently. The router core in the middle +implements spanning tree maintenance, bloom filter exchange, greedy routing, +session management, and Noise IK encryption. At the bottom, transport plugins +handle the physical diversity — each plugin implements the same interface, so the +router treats UDP, Ethernet, LoRa, Tor, and serial links identically. Adding a +new transport requires no changes to the routing or session layers. + ## Prior Work FIPS builds on proven designs rather than inventing new cryptography or routing @@ -402,8 +414,6 @@ A **transport** is a physical or logical interface: a UDP socket, an Ethernet NIC, a Tor client, a radio modem. A **link** is a connection instance to a specific peer over a transport. -![Transport Abstraction](fips-transport-abstraction.svg) - ### Multi-Transport Bridging A node with multiple transports automatically bridges between networks. Peers @@ -566,7 +576,7 @@ maintaining control over their own identities and peering relationships. | [fips-routing.md](fips-routing.md) | Bloom filters, discovery, greedy routing | | [spanning-tree-dynamics.md](spanning-tree-dynamics.md) | Tree protocol dynamics and convergence | | [fips-transports.md](fips-transports.md) | Transport protocol characteristics | -| [fips-architecture.md](fips-architecture.md) | Software architecture, configuration | +| [fips-software-architecture.md](fips-software-architecture.md) | Software architecture, configuration | ### External References diff --git a/docs/design/fips-transport-abstraction.svg b/docs/design/fips-node-architecture.svg similarity index 100% rename from docs/design/fips-transport-abstraction.svg rename to docs/design/fips-node-architecture.svg diff --git a/docs/design/fips-architecture.md b/docs/design/fips-software-architecture.md similarity index 100% rename from docs/design/fips-architecture.md rename to docs/design/fips-software-architecture.md diff --git a/docs/design/fips-transports.md b/docs/design/fips-transports.md index 3aa9aab..008f8dd 100644 --- a/docs/design/fips-transports.md +++ b/docs/design/fips-transports.md @@ -11,7 +11,7 @@ that FIPS can operate over. - **Link**: A connection instance to a specific peer over a transport This document describes transport-level characteristics. See -[fips-architecture.md](fips-architecture.md) for the Transport trait definition. +[fips-software-architecture.md](fips-software-architecture.md) for the Transport trait definition. ## Design Principles @@ -136,7 +136,7 @@ transport-layer connection before FIPS authentication can proceed. **Link lifecycle**: Connectionless transports use a trivial link model (no state machine). Connection-oriented transports require a real state machine: `Connecting → Connected → Disconnected`. See -[fips-architecture.md](fips-architecture.md) for link lifecycle details. +[fips-software-architecture.md](fips-software-architecture.md) for link lifecycle details. **Startup latency**: Connection-oriented transports add latency before a peer becomes usable. Tor is particularly slow (circuit setup). This affects peer @@ -168,7 +168,7 @@ NAT devices and firewalls, limiting deployment to networks without NAT. ## Transport Driver Interface > **Note**: The definitive Transport trait is defined in -> [fips-architecture.md](fips-architecture.md). This section provides a +> [fips-software-architecture.md](fips-software-architecture.md). This section provides a > simplified conceptual view. Each transport driver provides: diff --git a/docs/design/fips-wire-protocol.md b/docs/design/fips-wire-protocol.md index f35e676..99afc01 100644 --- a/docs/design/fips-wire-protocol.md +++ b/docs/design/fips-wire-protocol.md @@ -844,7 +844,7 @@ protocol layers apply additional policy. - [fips-intro.md](fips-intro.md) - Overall protocol design - [fips-session-protocol.md](fips-session-protocol.md) - Session establishment flow -- [fips-architecture.md](fips-architecture.md) - Software architecture +- [fips-software-architecture.md](fips-software-architecture.md) - Software architecture ### External References