Skip to content

Commit ad11b7f

Browse files
olaurendeauAntoLC
olaurendeau
authored and
AntoLC
committed
📝(docs) init architecture documentation
- Add docs about architecture - Add ADR about the CRDT choice
1 parent 3d5adad commit ad11b7f

File tree

2 files changed

+212
-0
lines changed

2 files changed

+212
-0
lines changed

‎docs/adr/ADR-0001-20250106-use-yjs-for-docs-editing.md

+193
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
## Decision TLDR;
2+
3+
We will use Yjs a CRDT-based library for the collaborative editing of the documents.
4+
5+
## Status
6+
7+
Accepted
8+
9+
## Context
10+
11+
We need to implement a collaborative editing feature for the documents that supports real-time collaboration, offline capabilities, and seamless integration with our Django backend.
12+
13+
## Considered alternatives
14+
15+
### ProseMirror
16+
17+
A robust toolkit for building rich-text editors with collaboration capabilities.
18+
19+
| Pros | Cons |
20+
| --- | --- |
21+
| Mature ecosystem | Complex integration with Django |
22+
| Rich text editing features | Steeper learning curve |
23+
| Used by major companies | More complex to implement offline support |
24+
| Large community | |
25+
26+
### ShareDB
27+
28+
Real-time database backend based on Operational Transformation.
29+
30+
| Pros | Cons |
31+
| --- | --- |
32+
| Battle-tested in production | Complex setup required |
33+
| Strong consistency model | Requires specific backend architecture |
34+
| Good documentation | Less flexible with different backends |
35+
| | Higher latency compared to CRDTs |
36+
37+
### Convergence
38+
39+
Complete enterprise solution for real-time collaboration.
40+
41+
| Pros | Cons |
42+
| --- | --- |
43+
| Full-featured solution | Commercial licensing |
44+
| Built-in presence features | Less community support |
45+
| Enterprise support | More expensive |
46+
| Good offline support | Overkill for basic needs |
47+
48+
### CRDT-based Solutions Comparison
49+
50+
A CRDT-based library specifically designed for real-time collaboration.
51+
52+
| Category | Pros | Cons |
53+
|----------|------|------|
54+
| Technical Implementation | • Native real-time collaboration<br>• No central conflict resolution needed<br>• Works well with Django backend<br>• Automatic state synchronization | • Learning curve for CRDT concepts<br>• More complex initial setup<br>• Additional metadata overhead |
55+
| User Experience | • Instant local updates<br>• Works offline by default<br>• Low latency<br>• Smooth concurrent editing | • Eventual consistency might cause brief inconsistencies<br>• UI must handle temporary conflicts |
56+
| Performance | • Excellent scaling with multiple users<br>• Reduced server load<br>• Efficient network usage<br>• Good memory optimization (especially Yjs) | • Slightly higher memory usage<br>• Initial state sync can be larger |
57+
| Development | • No need to build conflict resolution<br>• Simple integration with text editors<br>• Future-proof architecture | • Team needs to learn new concepts<br>• Fewer ready-made solutions<br>• May need to build some features from scratch |
58+
| Maintenance | • Less server infrastructure<br>• Simpler deployment<br>• Fewer points of failure | • Debugging can be more complex<br>• State management requires careful handling |
59+
| Business Impact | • Better offline support for users<br>• Scales well as user base grows<br>• No licensing costs (with Yjs) | • Initial development time might be longer<br>• Team training required |
60+
61+
#### Yjs
62+
- **Type**: State-based CRDT
63+
- **Implementation**: JavaScript/TypeScript
64+
- **Features**:
65+
- Rich text collaboration
66+
- Shared types (Array, Map, XML)
67+
- Binary encoding
68+
- P2P support
69+
- **Performance**: Excellent for text editing
70+
- **Memory Usage**: Optimized
71+
- **License**: MIT
72+
73+
#### Automerge
74+
- **Type**: Operation-based CRDT
75+
- **Implementation**: JavaScript/Rust
76+
- **Features**:
77+
- JSON-like data structures
78+
- Change history
79+
- Undo/Redo
80+
- Binary format
81+
- **Performance**: Good, with Rust backend
82+
- **Memory Usage**: Higher than Yjs
83+
- **License**: MIT
84+
85+
#### Legion
86+
- **Type**: State-based CRDT
87+
- **Implementation**: Rust with JS bindings
88+
- **Features**:
89+
- High performance
90+
- Memory efficient
91+
- Binary protocol
92+
- **Performance**: Excellent
93+
- **Memory Usage**: Very efficient
94+
- **License**: Apache 2.0
95+
96+
#### Diamond Types
97+
- **Type**: Operation-based CRDT
98+
- **Implementation**: TypeScript
99+
- **Features**:
100+
- Specialized for text
101+
- Small memory footprint
102+
- Simple API
103+
- **Performance**: Good for text
104+
- **Memory Usage**: Efficient
105+
- **License**: MIT
106+
107+
Comparison Table:
108+
109+
| Feature | Yjs | Automerge | Legion | Diamond Types |
110+
|---------|-----|-----------|--------|---------------|
111+
| Text Editing | ✅ Excellent | ✅ Good | ⚠️ Basic | ✅ Excellent |
112+
| Structured Data | ✅ | ✅ | ✅ | ⚠️ |
113+
| Memory Efficiency | ✅ High | ⚠️ Medium | ✅ Very High | ✅ High |
114+
| Network Efficiency | ✅ | ⚠️ | ✅ | ✅ |
115+
| Maturity | ✅ | ✅ | ⚠️ | ⚠️ |
116+
| Community Size | ✅ Large | ✅ Large | ⚠️ Small | ⚠️ Small |
117+
| Documentation | ✅ | ✅ | ⚠️ | ⚠️ |
118+
| Backend Options | ✅ Many | ✅ Many | ⚠️ Limited | ⚠️ Limited |
119+
120+
Key Differences:
121+
1. **Implementation Approach**:
122+
- Yjs: Optimized for text and rich-text editing
123+
- Automerge: General-purpose JSON CRDT
124+
- Legion: Performance-focused with Rust
125+
- Diamond Types: Specialized for text collaboration
126+
127+
2. **Performance Characteristics**:
128+
- Yjs: Best for text editing scenarios
129+
- Automerge: Good all-around performance
130+
- Legion: Excellent raw performance
131+
- Diamond Types: Optimized for text
132+
133+
3. **Ecosystem Integration**:
134+
- Yjs: Wide range of integrations
135+
- Automerge: Good JavaScript ecosystem
136+
- Legion: Limited but growing
137+
- Diamond Types: Focused on text editors
138+
139+
This analysis reinforces our choice of Yjs for the CRDT-based option as it provides:
140+
- Best-in-class text editing performance
141+
- Mature ecosystem
142+
- Active community
143+
- Excellent documentation
144+
- Wide range of backend options
145+
146+
## Decision
147+
148+
After evaluating the alternatives, we choose Yjs for the following reasons:
149+
150+
1. **Technical Fit:**
151+
- Native CRDT support ensures reliable collaboration
152+
- Excellent offline capabilities
153+
- Good performance characteristics
154+
- Flexible backend integration options
155+
156+
2. **Project Requirements Match:**
157+
- Easy integration with our Django backend
158+
- Supports our core collaborative features
159+
- Manageable learning curve for the team
160+
161+
3. **Community & Support:**
162+
- Active development
163+
- Growing community
164+
- Good documentation
165+
- Open source with MIT license
166+
167+
### Comparison of Key Features:
168+
169+
| Feature | Yjs (CRDT) | ProseMirror | ShareDB | Convergence |
170+
|---------|-----|-------------|----------|-------------|
171+
| Real-time Collaboration | ✅ | ✅ | ✅ | ✅ |
172+
| Offline Support | ✅ | ⚠️ | ⚠️ | ✅ |
173+
| Django Integration | Easy | Complex | Complex | Moderate |
174+
| Learning Curve | Medium | High | High | Medium |
175+
| Cost | Free | Free | Free | Paid |
176+
| Community Size | Growing | Large | Medium | Small |
177+
178+
## Consequences
179+
180+
### Positive
181+
- Simplified implementation of real-time collaboration
182+
- Good developer experience
183+
- Future-proof technology choice
184+
- No licensing costs
185+
186+
### Negative
187+
- Team needs to learn CRDT concepts
188+
- Newer technology compared to alternatives
189+
- May need to build some features available out-of-the-box in other solutions
190+
191+
### Risks
192+
- Community support might not grow as expected
193+
- May discover limitations as we scale

‎docs/architecture.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## Architecture
2+
3+
### Global system architecture
4+
5+
```mermaid
6+
flowchart TD
7+
User -- HTTP --> Front("Frontend (NextJS SPA)")
8+
Front -- REST API --> Back("Backend (Django)")
9+
Front -- WebSocket --> Yserver("Microservice Yjs (Express)") -- WebSocket --> CollaborationServer("Collaboration server (Hocuspocus)") -- REST API <--> Back
10+
Front -- OIDC --> Back -- OIDC ---> OIDC("Keycloak / ProConnect")
11+
Back -- REST API --> Yserver
12+
Back --> DB("Database (PostgreSQL)")
13+
Back <--> Celery --> DB
14+
Back ----> S3("Minio (S3)")
15+
```
16+
17+
### Architecture decision records
18+
19+
- [ADR-0001-20250106-use-yjs-for-docs-editing](./adr/ADR-0001-20250106-use-yjs-for-docs-editing.md)

0 commit comments

Comments
 (0)