Realtime Collaboration Notes

Project roadmap

1. 01

   Design the app

   ~2h

   Write DESIGN.md: teams, members, notes (title, body and lock_version), and revisions (note, author, body, created at and a summary of the change); how edits are sent (the client sends its full text or a patch with the version it started from), how conflicts are handled (a stale version is rejected and the client gets the latest text to merge), what is broadcast, and who may subscribe. Done when: DESIGN.md covers the data, sync and permissions.

2. 02

   Set up the app and permissions

   ~2h

   Create a Rails app with authentication (Rails' built-in generator or Devise), teams and memberships, and notes belonging to a team. Enforce that only team members can see and change a team's notes, in controllers and in one policy class (such as with Pundit). Configure Action Cable to use Redis. Done when: users only see their teams' notes, and other notes return 404.

3. 03

   Broadcast changes with Action Cable

   ~2.5h

   Create a NoteChannel that verifies the user (from the connection's identified user) belongs to the note's team before streaming for that note. When a note is saved, broadcast the new body, version and author. In the page, subscribe with the Action Cable JavaScript client and update the editor when others change the note, keeping the local cursor position. Done when: two browsers editing the same note see each other's changes within a second.

4. 04

   Detect conflicting edits

   ~2h

   Save edits with Rails' optimistic locking (lock_version), sent after the user pauses typing. When a save fails with StaleObjectError, send the latest text and version back, and in the browser merge simple non-overlapping changes automatically (for example with a diff library) or show both versions for the user to choose. Done when: two users typing in the same note at once never lose an edit without being told.

5. 05

   Keep revisions

   ~1.5h

   Create a revision on each save (grouping saves by the same user within a minute into one revision to avoid thousands of tiny ones). Build a history page listing revisions with author and time, a diff between any revision and the current text, and a restore button that creates a new revision. Done when: history shows who changed what, and restoring works.

6. 06

   Show presence

   ~1h

   Track who is currently viewing each note (in Redis, with expiry, updated by the channel's subscribed and unsubscribed callbacks and a periodic heartbeat), and show their names in the editor. Done when: opening a note in two browsers shows both users, and closing one removes it.

7. 07

   Test it

   ~2h

   Write tests: channel tests with ActionCable::Channel::TestCase (members can subscribe, others are rejected, and saves broadcast), model tests for optimistic locking and revision grouping, request tests for permissions, and a system test with two browser sessions editing the same note. Done when: bin/rails test passes.

Resources

• DocsAction Cable overview (Rails guides)
• DocsOptimistic locking in Active Record
• DocsPundit (authorization)
• DocsRedis pub/sub
• DocsTesting Rails applications: Action Cable