From 4aa1a38c9d0fceefc22b5e3364ab2b7527a7a675 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Sun, 19 Apr 2026 23:42:38 -0700
Subject: [PATCH] nfs diagram

---
 NFS-Server.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/NFS-Server.md b/NFS-Server.md
index a2efc09..1d1fafe 100644
--- a/NFS-Server.md
+++ b/NFS-Server.md
@@ -150,6 +150,48 @@ servers are not reachable from the NFS host.
 
 ## Architecture
 
+```mermaid
+flowchart LR
+    subgraph Clients["NFS clients"]
+        LinuxClient["Linux kernel<br/>nfs.ko (v3)"]
+        MacClient["macOS kernel<br/>nfsv3"]
+    end
+
+    subgraph NFSHead["weed nfs (NFSv3 head)"]
+        direction TB
+        RPC["NFSv3 / MOUNT RPC<br/>go-nfs backend"]
+        Handles["Deterministic filehandles<br/>exportID | kind | inode | gen"]
+        MetaSub["Metadata subscription<br/>(SubscribeMetadata)"]
+        Cache["Shared chunk reader cache"]
+        ACL["Client allowlist<br/>(CIDR / host)"]
+        RPC --> Handles
+        RPC --> Cache
+        MetaSub -. invalidate .-> Cache
+    end
+
+    subgraph Cluster["SeaweedFS cluster"]
+        direction TB
+        Filer["Filer<br/>metadata + AssignVolume"]
+        InodeIdx[("Inode secondary index<br/>inode -> paths, generation")]
+        Volumes["Volume servers<br/>chunk read / write"]
+        Filer --- InodeIdx
+        Filer -. AssignVolume .-> Volumes
+    end
+
+    LinuxClient -- "port=2049<br/>mountport=2049" --> RPC
+    MacClient -- "port=2049<br/>mountport=2049" --> RPC
+    ACL -. gate .-> RPC
+
+    Handles -- "lookup / readdir / create<br/>rename / remove / link" --> Filer
+    Handles -- "resolve inode -> path" --> InodeIdx
+    Filer -- "change events" --> MetaSub
+
+    RPC -- "chunk read / write<br/>(direct | publicUrl | filerProxy)" --> Volumes
+    RPC -. "inline <= 4 MiB fast path<br/>UpdateEntry only" .-> Filer
+```
+
+Request flow in one line: NFS RPC arrives at the head, the filehandle decodes into an inode, the filer resolves the inode through its secondary index for metadata work, and chunk bytes flow straight between the NFS head and the volume servers. The filer's `SubscribeMetadata` stream keeps the head's chunk cache coherent with other writers.
+
 ### Deterministic Filehandles
 
 Every filer entry in this PR now carries a filer-assigned inode