Rename design docs for clarity, reorganize node architecture diagram

- 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)
This commit is contained in:
Johnathan Corgan
2026-02-13 15:03:06 +00:00
parent 28af84d2f2
commit 73129f16d7
6 changed files with 23 additions and 13 deletions
+6 -6
View File
@@ -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
+13 -3
View File
@@ -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

Before

Width:  |  Height:  |  Size: 8.6 KiB

After

Width:  |  Height:  |  Size: 8.6 KiB

+3 -3
View File
@@ -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:
+1 -1
View File
@@ -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