|
1 | 1 | # CollabEdit |
2 | 2 |
|
3 | | -Real-time collaborative documents, in the spirit of Google Docs, with offline editing and |
4 | | -Git-style branches: fork a live document, work on it privately, and open a merge request. |
5 | | - |
6 | | -> **Status:** v2 rebuild in progress — phase 4 built (sharing and roles); deployment next, |
7 | | -> see [docs/DEPLOY.md](docs/DEPLOY.md). |
8 | | -> See [docs/PLAN.md](docs/PLAN.md). |
9 | | -> The original MERN version is preserved under the `v1` tag. |
| 3 | +Real-time collaborative documents, in the spirit of Google Docs: live cursors, offline editing, |
| 4 | +version history, full-text search and link sharing — on a sync server, storage layer and auth |
| 5 | +system written from scratch. Next up: Git-style branches, so you can fork a live document, work on |
| 6 | +it privately, and open a merge request. |
| 7 | + |
| 8 | +[](https://github.com/Aditya-XR/collaborative-editor/actions/workflows/ci.yml) |
| 9 | + **[Live demo](https://collaborative-editor-flax.vercel.app)** · [Plan and progress](docs/PLAN.md) · |
| 10 | +[Architecture decisions](docs/adr) · [Deployment](docs/DEPLOY.md) |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +> **Status:** live on Vercel (web) and Render (API) with Neon Postgres and Redis Cloud. Phases 0–4 |
| 15 | +> of the [v2 plan](docs/PLAN.md) are done — accounts, live editing with offline support, compaction, |
| 16 | +> version history, search and sharing. Still to come: branches and merge requests, comments, |
| 17 | +> multi-instance Redis. The original MERN version is preserved under the |
| 18 | +> [`v1` tag](https://github.com/Aditya-XR/collaborative-editor/tree/v1). |
| 19 | +> |
| 20 | +> The free API instance is kept awake 08:00–24:00 IST; outside those hours the first request can |
| 21 | +> take up to a minute while it wakes. |
| 22 | +
|
| 23 | +## Highlights |
| 24 | + |
| 25 | +- **Own sync server.** FastAPI WebSockets speak the Yjs sync and awareness protocols on top of |
| 26 | + pycrdt (Rust Yrs): one room per open document, per-connection send queues, and roles enforced on |
| 27 | + every update ([ADR 0012](docs/adr/0012-sync-server-on-pycrdt.md)). In production, edits reach |
| 28 | + other users in about 110 ms. |
| 29 | +- **Edit log + compaction.** Edits are batched into an append-only Postgres log (every 500 ms or |
| 30 | + 50 updates) and folded into snapshots under an advisory lock. Opening a 10,000-keystroke document |
| 31 | + went from **218 ms to 17 ms**, and a 50,000-keystroke one from 6.5 s to 0.28 s |
| 32 | + ([ADR 0003](docs/adr/0003-edit-log-and-snapshots.md)). |
| 33 | +- **Self-built rate limiter.** A token bucket in one Redis Lua script: atomic across API |
| 34 | + instances in a single round trip, failing open or closed per policy |
| 35 | + ([ADR 0005](docs/adr/0005-token-bucket-rate-limiter.md)). |
| 36 | +- **Careful sessions.** Argon2id passwords, 15-minute JWTs, rotating refresh tokens with reuse |
| 37 | + detection ([ADR 0011](docs/adr/0011-sessions-and-refresh-rotation.md)), and one-time 30-second |
| 38 | + WebSocket tickets ([ADR 0006](docs/adr/0006-websocket-tickets.md)). |
| 39 | +- **Offline-first.** The browser keeps an IndexedDB copy of each document; edits made offline merge |
| 40 | + when the connection returns, and the copies are wiped on sign-out or when access is revoked. |
| 41 | +- **Tested.** 173 API tests against real Postgres and Redis — including Hypothesis properties for |
| 42 | + CRDT convergence and compaction — and 79 web tests, all run by GitHub Actions on every push. |
| 43 | + |
| 44 | +## Architecture |
| 45 | + |
| 46 | +```mermaid |
| 47 | +flowchart TB |
| 48 | + subgraph Browser |
| 49 | + direction LR |
| 50 | + UI["React + Tiptap"] --- YD["Yjs document"] --- IDB[("IndexedDB copy")] |
| 51 | + end |
| 52 | + subgraph API["FastAPI on Render"] |
| 53 | + direction LR |
| 54 | + REST["REST API<br/>auth · documents · sharing · versions · search"] |
| 55 | + ROOMS["Sync rooms<br/>pycrdt, one per open document"] |
| 56 | + end |
| 57 | + subgraph Data["Managed data"] |
| 58 | + direction LR |
| 59 | + PG[("PostgreSQL<br/>edit log + snapshots")] |
| 60 | + RD[("Redis<br/>rate limits · WebSocket tickets")] |
| 61 | + end |
| 62 | + UI -- "HTTPS /api · JWT" --> REST |
| 63 | + YD <-- "WebSocket · Yjs sync + awareness" --> ROOMS |
| 64 | + REST --> PG |
| 65 | + ROOMS -- "batched edits" --> PG |
| 66 | + REST --> RD |
| 67 | + ROOMS --> RD |
| 68 | +``` |
10 | 69 |
|
11 | 70 | ## Stack |
12 | 71 |
|
|
0 commit comments