From 9e77d56822ab03191ab3d99ea29985f47ef9807b Mon Sep 17 00:00:00 2001
From: mik-tf <mik-tf@users.noreply.github.com>
Date: Thu, 16 Oct 2025 14:31:27 -0400
Subject: [PATCH] feat: Add comprehensive Mycelium network architecture
 documentation

---
 docs/mycelium-network/architecture.md | 225 ++++++++++++++++++++++++++
 docs/mycelium-network/install.md      |   2 +-
 docs/mycelium-network/overview.md     |  12 +-
 sidebars.js                           |   1 +
 4 files changed, 234 insertions(+), 6 deletions(-)
 create mode 100644 docs/mycelium-network/architecture.md

diff --git a/docs/mycelium-network/architecture.md b/docs/mycelium-network/architecture.md
new file mode 100644
index 0000000..7efa74a
--- /dev/null
+++ b/docs/mycelium-network/architecture.md
@@ -0,0 +1,225 @@
+---
+sidebar_position: 4
+---
+
+# Mycelium Network Architecture
+
+Understanding Mycelium's architecture reveals why it's fundamentally different from traditional networking solutions.
+
+## Core Innovation: Identity = Address
+
+Mycelium's architecture revolves around **peers**. Each peer has a cryptographic private/public keypair, and these are used to encrypt all messages in an end-to-end fashion.
+
+The hash of the public key is used as an **IPv6 address**. This means that the cryptographic identity and the network address of each peer are **inherently linked**.
+
+### What This Means in Practice
+
+Think of it like a postal system where you can send a secret message to anyone just by knowing their address. The recipient can read it simply because they reside at the intended destination, without requiring any additional coordination or precommunication.
+
+- **Your address IS your identity** - No separation between who you are and where you are
+- **Automatic encryption** - Messages are encrypted to the destination by design
+- **No key exchange needed** - The address itself contains the encryption key
+
+<div className="info-box">
+
+### 🔐 Technical Lineage
+
+This innovation was pioneered by the **cjdns** network, which later inspired **Yggdrasil**, from which Mycelium is inspired. Each generation has refined and improved upon this fundamental concept.
+
+</div>
+
+## Why This Is More Secure Than TLS/HTTPS
+
+Compare this to the regular web, where most traffic is encrypted using TLS/HTTPS:
+
+### The TLS Problem
+
+In traditional TLS/HTTPS:
+
+- ❌ **No inherent link** between a TLS cryptographic identity (certificate) and the destination of the traffic
+- ❌ **Self-signed certificates** are rare and not considered secure (without identity-destination link, impossible to know if created by a MITM attacker)
+- ❌ **Centralized certificate authorities** - Internet devices must be loaded with a list of trusted CAs
+- ❌ **Single points of failure** - CAs can be compromised, fail, or be coerced
+
+### The Mycelium Solution
+
+✅ **Cryptographic identity = Network address** - MITM attacks are cryptographically impossible  
+✅ **No trusted intermediaries** - No certificate authorities to compromise  
+✅ **Decentralized by design** - No single point of failure  
+✅ **Improved security AND resiliency** - Both benefits simultaneously
+
+## Network Architecture: Underlay & Overlay
+
+Mycelium creates a **mesh network** to deliver encrypted IP overlay traffic. But how do peers actually connect?
+
+### The Underlay Network
+
+Mycelium peers must connect somehow to form the mesh. Most commonly, peers connect **over the regular internet**, using it as an **underlay network**.
+
+This is enabled by **public peers** - special nodes that are open to receive connections on the regular internet.
+
+```
+┌──────────────────────────────────────────────────┐
+│            Regular Internet (Underlay)           │
+│                                                  │
+│  ┌──────────┐     ┌──────────┐     ┌──────────┐  │
+│  │ Public   │     │ Public   │     │ Public   │  │
+│  │ Peer A   │     │ Peer B   │     │ Peer C   │  │
+│  └────▲─────┘     └────▲─────┘     └────▲─────┘  │
+│       │                │                │        │
+└───────┼────────────────┼────────────────┼────────┘
+        │                │                │
+    ┌───┴────┐       ┌───┴────┐       ┌───┴────┐
+    │ Your   │◄─────►│ Your   │◄─────►│ Your   │
+    │Device 1│  Mesh │Device 2│ Mesh  │Device 3│
+    └────────┘       └────────┘       └────────┘
+         Encrypted Mycelium Overlay Network
+```
+
+### The Overlay Network
+
+On top of the underlay, Mycelium creates an **encrypted overlay** where:
+
+- All traffic between your devices is end-to-end encrypted
+- Routing is handled by the mesh protocol
+- Your devices appear to be on the same local IPv6 network
+
+## Resilient Multi-Path Routing
+
+Here's where Mycelium achieves **more resilient routing than the regular internet**:
+
+### How It Works
+
+Each peer generally connects to **multiple public peers**, each offering a **different potential path** for traffic.
+
+```
+         ┌────────────────┐
+         │  Your Device   │
+         └───┬─────┬─────┬┘
+             │     │     │
+    ┌────────┤     │     └────────┐
+    │              │              │
+┌───▼────┐     ┌───▼────┐    ┌────▼───┐
+│Public  │     │Public  │    │Public  │
+│Peer 1  │     │Peer 2  │    │Peer 3  │
+│Germany │     │Belgium │    │Finland │
+└────────┘     └────────┘    └────────┘
+  Route A        Route B       Route C
+```
+
+### Real-World Resilience
+
+If the route via one public peer is interrupted—such as by an **undersea cable cut**—there's a possibility to find another route via another public peer.
+
+<div className="info-box">
+
+### 🌊 Real Example
+
+This isn't just theoretical. We have experienced interruptions that were traceable with good certainty to **undersea cable cuts** happening at the same time. The network automatically routed around the failure using alternative paths.
+
+</div>
+
+**Why the regular internet can't do this:**
+
+- Most internet connections have a single ISP path
+- BGP routing changes slowly and requires coordination
+- No automatic multi-path at the user level
+- Cable cuts can disconnect entire regions
+
+**Why Mycelium can:**
+
+- You're connected to multiple geographically diverse peers
+- Mesh routing adapts automatically in seconds
+- No coordination needed—it's peer-to-peer
+- Traffic flows through available paths automatically
+
+## Key Architectural Components
+
+### 1. Cryptographic Keypair
+
+Every Mycelium node generates:
+- **Private key** - Kept secret, never shared
+- **Public key** - Shared openly, identifies your node
+
+### 2. IPv6 Address
+
+Derived from your public key:
+- **Format**: Standard IPv6 (e.g., `5c4:c176:bf44:b2ab:5e7e:f6a:b7e2:11ca`)
+- **Unique**: Cryptographically guaranteed to be unique
+- **Persistent**: Doesn't change unless you generate new keys
+
+### 3. Peer Connections
+
+Your node maintains connections to:
+- **Public peers** - For internet connectivity and routing
+- **Direct peers** - Other nodes you explicitly connect to
+- **Discovered peers** - Nodes found through the mesh
+
+### 4. Routing Table
+
+Each node maintains:
+- **Known peers** and their addresses
+- **Path costs** to reach each peer
+- **Multiple routes** to most destinations
+- **Automatic updates** as the network changes
+
+## Message Encryption Flow
+
+When you send data to another Mycelium address:
+
+1. **Lookup destination** - Find the IPv6 address
+2. **Derive public key** - Extract from the address
+3. **Encrypt message** - Using the destination's public key
+4. **Route through mesh** - Via optimal path
+5. **Decrypt at destination** - Using their private key
+
+Only the destination can decrypt—not even the public peers can read the content.
+
+## Benefits of This Architecture
+
+### Security Benefits
+
+- **End-to-end encryption** - Built into the protocol
+- **No MITM attacks** - Identity = Address prevents it
+- **No trusted third parties** - Fully peer-to-peer
+- **Private by default** - Encryption isn't optional
+
+### Resilience Benefits
+
+- **Multi-path routing** - Automatic failover
+- **Self-healing** - Network adapts to failures
+- **No single point of failure** - Fully distributed
+- **Works behind NAT** - Firewall traversal built-in
+
+### Simplicity Benefits
+
+- **Zero configuration** - Just run and connect
+- **Automatic key management** - No manual setup
+- **Plug and play** - Works immediately
+- **Cross-platform** - Same protocol everywhere
+
+## Comparison with Other Technologies
+
+| Feature | Mycelium | Traditional VPN | TLS/HTTPS | Tor |
+|---------|----------|----------------|-----------|-----|
+| **Identity = Address** | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| **Decentralized** | ✅ Yes | ❌ Central server | ❌ Needs CAs | ✅ Yes |
+| **Multi-path routing** | ✅ Yes | ❌ Single path | ❌ Single path | ✅ Yes |
+| **Direct connections** | ✅ When possible | ❌ Via server | ✅ Yes | ❌ Via relays |
+| **Zero config** | ✅ Yes | ❌ Needs setup | ✅ Browser only | ❌ Complex |
+| **Performance** | ✅ Fast | ⚠️ Moderate | ✅ Fast | ❌ Slow |
+
+## Technical Resources
+
+For more technical details:
+
+- **Source Code**: [github.com/threefoldtech/mycelium](https://github.com/threefoldtech/mycelium)
+- **Yggdrasil Network**: [yggdrasil-network.github.io](https://yggdrasil-network.github.io/)
+- **cjdns Project**: [github.com/cjdelisle/cjdns](https://github.com/cjdelisle/cjdns)
+
+---
+
+:::tip Understanding Makes It Powerful
+
+Now that you understand how Mycelium works, you can appreciate why it's not just another VPN—it's a fundamentally different approach to secure networking that eliminates entire classes of security problems.
+:::
diff --git a/docs/mycelium-network/install.md b/docs/mycelium-network/install.md
index ed89bff..8658a23 100644
--- a/docs/mycelium-network/install.md
+++ b/docs/mycelium-network/install.md
@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# Install Mycelium
+# Install Mycelium Network
 
 The Mycelium app is available for Android, Windows, macOS, and iOS. Installation is simple and user-friendly!
 
diff --git a/docs/mycelium-network/overview.md b/docs/mycelium-network/overview.md
index a6e8cbc..a315a30 100644
--- a/docs/mycelium-network/overview.md
+++ b/docs/mycelium-network/overview.md
@@ -122,20 +122,23 @@ Connect to services on the ThreeFold Grid:
 ## Architecture Overview
 
 ```
-┌──────────────┐      Encrypted Tunnel      ┌──────────────┐
+┌──────────────┐      Encrypted Tunnel        ┌──────────────┐
 │   Device A   │◄────────────────────────────►│   Device B   │
-│ Mycelium IP  │      Over Internet          │ Mycelium IP  │
-└──────────────┘                             └──────────────┘
+│ Mycelium IP  │      Over Internet           │ Mycelium IP  │
+└──────────────┘                              └──────────────┘
        │                                            │
-       └────────────── Mesh Network ───────────────┘
+       └────────────── Mesh Network ────────────────┘
                    (via Public Peers)
 ```
 
+**How it works:**
 - Devices run Mycelium daemon
 - Connect to public or private peers
 - Build encrypted tunnels automatically
 - Route traffic efficiently
 
+**Want to understand the architecture in depth?** Read the **[Architecture Guide](/getstarted/mycelium-network/architecture)** to learn about Mycelium's innovative cryptographic design, why it's more secure than TLS/HTTPS, and how its multi-path routing provides real-world resilience.
+
 ## Getting Started
 
 Ready to try Mycelium? It's super easy:
@@ -157,7 +160,6 @@ Ready to try Mycelium? It's super easy:
 
 ## Resources
 
-- **Documentation**: [Mycelium Guide](https://threefoldtech.github.io/www_myceliumguide/)
 - **Source Code**: [GitHub Repository](https://github.com/threefoldtech/mycelium)
 - **Community**: [ThreeFold Telegram](https://t.me/threefold/1)
 - **Forum**: [forum.threefold.io](https://forum.threefold.io)
diff --git a/sidebars.js b/sidebars.js
index bbf6ab3..c47c391 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -41,6 +41,7 @@ const sidebars = {
       },
       items: [
         'mycelium-network/overview',
+        'mycelium-network/architecture',
         'mycelium-network/install',
         'mycelium-network/quick-start',
       ],