Skip to content

Commit eaa4b8b

Browse files
committed
docs: README with live demo, screenshot, highlights and architecture
1 parent 075528e commit eaa4b8b

2 files changed

Lines changed: 66 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 66 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,71 @@
11
# CollabEdit
22

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+
[![CI](https://github.com/Aditya-XR/collaborative-editor/actions/workflows/ci.yml/badge.svg?branch=main)](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+
![Two people editing the same document: Rahul's caret and name appear live in Priya's window, with both avatars and "All changes synced" in the header](docs/screenshots/editor.png)
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+
```
1069

1170
## Stack
1271

‎docs/screenshots/editor.png‎

234 KB
Loading

0 commit comments

Comments
 (0)