mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +00:00
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:
@@ -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
|
||||
|
||||
@@ -79,6 +79,18 @@ encryption transparently in either case.
|
||||
|
||||
See [fips-transports.md](fips-transports.md) for transport options and characteristics.
|
||||
|
||||

|
||||
|
||||
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.
|
||||
|
||||

|
||||
|
||||
### 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 |
@@ -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:
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user