Could anyone help me to visualize how Yjs works?

I am new to Yjs and I am mesmerized by its amazing concepts and performance.
Now I am trying to make my cloned Notion projects but I am having hard time even to understand how it works.

Here it is my drawing and I want to make it sure I understood it correctly.

  1. Clients open the web, web internally connects client to the network layer (in my case, it is WebSocket) and it loads data from the persistence layer (IndexedDB here).
  2. Now clients are ready to fire events, and when he edits, edits are fired and propagates via network layer.

If above is correct what I am wondering is where and when and how do I store the data in centralized server. I think I misunderstood something on it, but I don’t even recognize what I don’t know. Enlighten me please.

Initially yjs can appear straighforward yet quite confusing until you start playing around with the library with very simple examples. Unless you’ve done this, my suggestion would be to start by building simple programs without actually using actual networking or databases, and learn how shared data types work, how documents are created, modified, synced etc. This understanding will help you tackle more complex interactions.

1 Like

@choikangjae More like this:

  • Data is only persisted to a storage medium (red) via providers (blue).
  • Providers replicate data across different Y.Docs. Providers are necessary for all persistence and network transport.

It should be clear from the above diagram that a provider running on the server can store data in a centralized database. Just wire it up as described in the docs and it will happily replicate any updates while it is connected.

const mdb = new MongodbPersistence(createConnectionString("yjstest"), {
	collectionName: "transactions",
	flushSize: 100,
	multipleCollections: true,


Wow after I saw your drawing, everything got so clear. It helped me a lot. Thanks a bunch!

1 Like