I will refrain from adding yet another “please document syncthing architecture” issue on github like others did (only to see it closed) and instead try posting here.
This project is of great interest and has already a certain age and maturity, but there’s still no document that explains how syncthing actually works!
Although I know something about software engineering, networking, and specifically synchronization software, I still fail to develop a clear mental model of syncthing. Short of reading the source, I think that I have intensely browsed all the available information (documentation, forum).
The “getting started” guide barely explains how syncthing works, while the “specifications” section focuses on technical details of messages while neglecting the big picture. Some information can be extracted from “usage” by reading between the lines, but all of this is not sufficient, at least for me.
For example, from the various bits that I have found it seems to me that syncthing does something more than realtime pairwise synchronization (=running unison continuously on the same network of peers). It seems to me that after a cluster has been established, the different members of a cluster first exchange their index databases until everybody has a view of the complete situation. Then each peer decides which files it needs to get (how exactly?) and from where and tries to obtain them (How? What if peer A wants the file from peer C, but it’s only connected directly to peer B?). I do not know whether this understanding is correct, but even if it is, it is still unclear to me what happend when files are modified during synchronization.
I think that a design document on syncthing would be very helpful for advanced users and would motivate contributions.