From 5804c2160183d26096b399632125eca01e28cb8f Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Mon, 19 Jan 2026 15:27:11 +0800
Subject: README: Document architectual considerations

---
 README.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index bd35eba8..c44b9104 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,17 @@ on a `Intel(R) Core(TM) i5-10210U CPU @ 1.60GHz`.
 **Note:** go-git is expected to perform much better after
 [storage: filesystem/mmap, Add PackScanner to handle large repos](https://github.com/go-git/go-git/pull/1776).
 
+## Architectural considerations
+
+It is important to realize that Furgit, and performant Git implementations in
+general, heavily rely on using memory mappings of packfiles, and assume
+relatively predictable fault handling behavior. Therefore, in distributed
+systems, we strongly advise *not* using Furgit on top of distributed network
+filesystems such as CephFS or NFS; instead, consider solutions where redundancy
+and distributions belong *above* the Git layer, such as using a set of Git
+nodes each running Furgit/etc. on local repositories, then using an RPC
+protocol over it.
+
 ## Dependencies
 
 * The standard library
-- 
cgit v1.3.1-10-gc9f91