From 474a43a398f703d4ed51e3bf5d8dd244dbae5853 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Mon, 20 Apr 2026 00:11:28 -0700
Subject: [PATCH] Update P2P-reading-in-weed-mount.md

---
 P2P-reading-in-weed-mount.md | 44 ++++++++++++++++++++++++------------
 1 file changed, 30 insertions(+), 14 deletions(-)

diff --git a/P2P-reading-in-weed-mount.md b/P2P-reading-in-weed-mount.md
index 5e19c5f..4884a2a 100644
--- a/P2P-reading-in-weed-mount.md
+++ b/P2P-reading-in-weed-mount.md
@@ -9,24 +9,40 @@ The design is documented in [design-weed-mount-peer-chunk-sharing.md](https://gi
 ## How it works at a glance
 
 ```mermaid
-flowchart TB
-    Filer["Filer(s)<br/>mount registry"]
-    MountA["weed mount A"]
-    MountB["weed mount B"]
-    MountC["weed mount C"]
+flowchart LR
+    Filer["Filer<br/>mount registry"]
+    Mounts["weed mount fleet<br/>(peer directory + cache)"]
     Volumes["Volume servers"]
 
-    MountA -- "MountRegister / MountList" --> Filer
-    MountB -- "MountRegister / MountList" --> Filer
-    MountC -- "MountRegister / MountList" --> Filer
+    Mounts -- "register / list" --> Filer
+    Mounts <-- "announce / lookup / fetch" --> Mounts
+    Mounts -. "fallback" .-> Volumes
+```
 
-    MountA <-- "ChunkAnnounce / Lookup / FetchChunk" --> MountB
-    MountB <-- "ChunkAnnounce / Lookup / FetchChunk" --> MountC
-    MountA <-- "ChunkAnnounce / Lookup / FetchChunk" --> MountC
+### Chunk read sequence
 
-    MountA -. "fallback on any failure" .-> Volumes
-    MountB -. "fallback on any failure" .-> Volumes
-    MountC -. "fallback on any failure" .-> Volumes
+```mermaid
+sequenceDiagram
+    participant K as Kernel (FUSE read)
+    participant R as Mount (reader)
+    participant O as Mount (HRW owner)
+    participant H as Mount (holder)
+    participant V as Volume server
+
+    K->>R: read(chunk fid)
+    R->>O: ChunkLookup(fid)
+    alt holders known
+        O-->>R: [holder, ...]
+        R->>H: FetchChunk(fid)
+        H-->>R: chunk bytes
+        R->>R: verify MD5 vs filer ETag
+        R-->>K: bytes
+    else no holders / any failure
+        R->>V: HTTP chunk read
+        V-->>R: chunk bytes
+        R-->>K: bytes
+        R->>O: ChunkAnnounce(fid, self)
+    end
 ```
 
 * **Tier 1 — filer registry.** Each filer holds a tiny in-memory map of which mounts are alive. Mounts broadcast `MountRegister` to **every** configured filer, and merge every filer's `MountList` response by `peer_addr` (newest `last_seen_ns` wins). That way two mounts pointing at different filers still see each other even though no filer-to-filer sync exists.