Skip to content

Use Automerge doc for user state#976

Open
kasbah wants to merge 52 commits intomainfrom
kb/automerge-user-state
Open

Use Automerge doc for user state#976
kasbah wants to merge 52 commits intomainfrom
kb/automerge-user-state

Conversation

@kasbah
Copy link
Member

@kasbah kasbah commented Jan 30, 2026

This is ready for review but I suggest we wait for "Performance regression on main" (automerge/automerge#1159) to be resolved before deploying to production. As it stands it takes 100ms to create a new user state when the user first visits the site which manifest in a delay of seeing any documents if cold visiting /documents.

Closes the "server side state" part of #881 by implementing Automerge docs, derived from the db data, for every user state. Mutations are still handled through regular RPC calls. The UserState mainly holds the document lists and some user information and is put into a Context on the frontend.

I couldn't resist slightly improving the UI of "My documents" and "Trash" since I had to replace them anyway. The overall feeling of reactivity of the document titles and the user names is very nice.

image

I am not sure how useful it is, but inspired by Benjamin Pierce's Colloquium talk, I made a commutative diagram of the paths I used property based testing on.

image
$$t_1$$ write_user_state_to_db Writes a UserState to the database (testing only).
$$f_1$$ read_user_state_from_db Reads a UserState from the database.
$$f_2$$ run_user_state_subscription Listens for Postgres notifications related to user state changes.
$$g$$ user_state_to_automerge Converts a UserState into an Automerge document.
$$t_2$$ automerge_to_user_state Converts an Automerge document to a UserState (testing only).

Note that run_user_state_subscription will be fine in normal usage but if you e.g. use ALTER TABLE by loading a dump or something the automerge doc will be inconsistent with the DB. read_user_state_from_db is run on request at the start so re-starting the server will fix the inconsistencies.

Here is a very imperfect schema for the UserState. (Imperfect since we can't really represent Vec<T> or Option<T> where T is an entity in the schema on CatColab -- also papering over how things are referred to, directly or via ID.)

https://catcolab.org/model/019cae54-2940-7971-9060-dcd2b8657ff5/analysis/019cae83-2b0a-7062-85a8-ceb4d1665c46

UserState - ERD(4)

@github-actions github-actions bot temporarily deployed to netlify-preview January 30, 2026 19:23 Destroyed
@kasbah kasbah force-pushed the kb/automerge-user-state branch from df280da to 00d279a Compare January 30, 2026 19:24
@github-actions github-actions bot temporarily deployed to netlify-preview January 30, 2026 19:24 Destroyed
@epatters epatters added enhancement New feature or request backend Backend, including web server and database labels Jan 30, 2026
@kasbah kasbah force-pushed the kb/automerge-user-state branch from 00d279a to c402121 Compare January 30, 2026 21:10
@github-actions github-actions bot temporarily deployed to netlify-preview January 30, 2026 21:10 Destroyed
@kasbah kasbah force-pushed the kb/automerge-user-state branch from c402121 to 27fe54c Compare January 31, 2026 00:35
@github-actions github-actions bot temporarily deployed to netlify-preview January 31, 2026 00:35 Destroyed
@kasbah kasbah force-pushed the kb/automerge-user-state branch from 27fe54c to ad099f8 Compare January 31, 2026 00:39
@github-actions github-actions bot temporarily deployed to netlify-preview January 31, 2026 00:39 Destroyed
@epatters epatters changed the title Use automerge for user state Use Automerge doc for user state Jan 31, 2026
@kasbah kasbah force-pushed the kb/automerge-user-state branch from ad099f8 to 7585fda Compare February 9, 2026 14:30
@kasbah kasbah force-pushed the kb/automerge-user-state branch from 2ecfdfa to dacf036 Compare February 9, 2026 14:57
@github-actions github-actions bot temporarily deployed to netlify-preview February 9, 2026 15:04 Destroyed
@github-actions github-actions bot temporarily deployed to netlify-preview February 9, 2026 15:20 Destroyed
@github-actions github-actions bot temporarily deployed to netlify-preview February 9, 2026 15:54 Destroyed
@kasbah kasbah force-pushed the kb/automerge-user-state branch from 9dbbd8c to 4ff0d67 Compare February 9, 2026 15:56
@github-actions github-actions bot temporarily deployed to netlify-preview February 9, 2026 15:56 Destroyed
@kasbah kasbah force-pushed the kb/automerge-user-state branch 2 times, most recently from 6426e7f to 5ee73ad Compare February 25, 2026 14:34
@github-actions github-actions bot temporarily deployed to netlify-preview February 25, 2026 14:40 Destroyed
@kasbah kasbah force-pushed the kb/automerge-user-state branch from 5ee73ad to 460bdcd Compare February 25, 2026 14:57
@github-actions github-actions bot temporarily deployed to netlify-preview February 25, 2026 14:59 Destroyed
@kasbah kasbah force-pushed the kb/automerge-user-state branch from 460bdcd to c42ac50 Compare February 25, 2026 15:02
@kasbah kasbah force-pushed the kb/automerge-user-state branch 4 times, most recently from 96d6f9b to 157f316 Compare March 4, 2026 18:06
@kasbah kasbah force-pushed the kb/automerge-user-state branch 2 times, most recently from 157bbc5 to 65c4619 Compare March 4, 2026 18:24
@kasbah kasbah force-pushed the kb/automerge-user-state branch from 65c4619 to 13c58ff Compare March 4, 2026 18:30
@kasbah kasbah force-pushed the kb/automerge-user-state branch from f45ed7b to 52108b9 Compare March 5, 2026 10:10
@kasbah
Copy link
Member Author

kasbah commented Mar 5, 2026

I realized it should just be a state_doc_id column in the users table. I also refactored to call it "state doc ID" everywhere instead of "state doc URL".

@epatters
Copy link
Member

epatters commented Mar 5, 2026

Great, I'll do another round of review soon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend Backend, including web server and database enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants