RFC (Request for Comments) Template

RFC (Request for Comments) Template

RFCs provide a structured way to propose, discuss, and reach consensus on significant technical changes. Unlike ADRs which document decisions already made, RFCs facilitate the decision-making process itself.

Why Use RFCs?

Benefits:

• Encourages thoughtful design before implementation
• Enables asynchronous collaboration across teams
• Creates a record of the decision-making process
• Surfaces concerns and edge cases early
• Builds consensus before committing resources

When to write an RFC:

• New features with significant scope
• Major architectural changes
• Cross-team initiatives
• Process changes affecting multiple teams
• Breaking changes to APIs or interfaces
• New technology adoption

The Template

# RFC: [Title]

**RFC ID:** RFC-[YYYY]-[NNN]
**Author(s):** [Names]
**Status:** [Draft | In Review | Accepted | Rejected | Withdrawn | Superseded]
**Created:** [YYYY-MM-DD]
**Last Updated:** [YYYY-MM-DD]

## Summary

[2-3 sentence summary of what this RFC proposes]

## Motivation

### Problem Statement

[What problem are we solving? Why is this important now?]

### Goals

- [Goal 1]
- [Goal 2]
- [Goal 3]

### Non-Goals

- [Explicitly out of scope item 1]
- [Explicitly out of scope item 2]

## Background

[Context needed to understand the proposal. Include:
- Current state of the system
- Previous related work
- Relevant constraints]

## Proposal

### Overview

[High-level description of the proposed solution]

### Detailed Design

[Technical details of the implementation:
- Architecture changes
- API changes
- Data model changes
- User-facing changes]

### Example Usage

[Code samples or user flows showing how this would work]

```typescript
// Example code demonstrating the proposal

Alternatives Considered

Alternative 1: [Name]

[Description and why it wasn't chosen]

Alternative 2: [Name]

[Description and why it wasn't chosen]

Implementation Plan

Phases

Phase 1: [Name]

• Task 1
• Task 2

Phase 2: [Name]

• Task 3
• Task 4

Dependencies

• [External dependency 1]
• [Team dependency 1]

Rollout Strategy

[How will this be rolled out? Feature flags? Gradual rollout?]

Risks and Mitigations

Success Metrics

Open Questions

• [Question 1 that needs resolution]
• [Question 2 that needs resolution]

References

• [Link to related documents]
• [Link to prior art/research]

Feedback

Reviewers

Discussion Summary

[Summary of key discussion points and how they were resolved]

## Complete Example

```markdown
# RFC: Implement Real-Time Collaboration

**RFC ID:** RFC-2025-042
**Author(s):** Sarah Chen, Mike Johnson
**Status:** In Review
**Created:** 2025-10-10
**Last Updated:** 2025-10-14

## Summary

This RFC proposes adding real-time collaboration features to our document editor, allowing multiple users to edit documents simultaneously with live cursor positions and presence indicators.

## Motivation

### Problem Statement

Users currently cannot collaborate on documents in real-time. When multiple team members need to work on the same document, they must coordinate manually to avoid conflicts, leading to:
- Lost work from overwrites
- Delayed collaboration (waiting for others to finish)
- Poor user experience compared to competitors
- Customer complaints (23 support tickets in last quarter)

### Goals

- Enable multiple users to edit documents simultaneously
- Show real-time cursor positions and selections
- Display presence indicators (who's viewing/editing)
- Maintain data consistency across all clients
- Support offline editing with conflict resolution

### Non-Goals

- Voice/video chat integration (separate RFC)
- Version history visualization (existing feature covers this)
- Mobile app support (Phase 2, out of scope for this RFC)
- Comments and suggestions (existing feature)

## Background

Our document editor was built in 2022 as a single-user experience. The architecture uses:
- React frontend with draft-js for rich text
- REST API for document CRUD operations
- PostgreSQL for document storage
- Redis for caching

We evaluated adding collaboration in Q3 2024 but deferred due to backend rewrite priority.

Competitors (Notion, Google Docs, Coda) all offer real-time collaboration as table stakes.

## Proposal

### Overview

Implement real-time collaboration using Conflict-free Replicated Data Types (CRDTs) with a WebSocket-based sync layer.

Architecture:

┌─────────────┐ WebSocket ┌─────────────┐ │ Client │◄──────────────────►│ Sync │ │ (Browser) │ │ Server │ └─────────────┘ └──────┬──────┘ │ ┌──────▼──────┐ │ Redis │ │ Pub/Sub │ └──────┬──────┘ │ ┌──────▼──────┐ │ PostgreSQL │ └─────────────┘

### Detailed Design

**1. CRDT Implementation**

Use Yjs library for CRDT operations. Each document becomes a Y.Doc with:
- Y.Text for document content
- Y.Map for document metadata
- Y.Array for embedded objects (images, tables)

```typescript
import * as Y from 'yjs';
import { WebsocketProvider } from 'y-websocket';

const ydoc = new Y.Doc();
const provider = new WebsocketProvider(
  'wss://sync.example.com',
  'document-123',
  ydoc
);

const ytext = ydoc.getText('content');
ytext.observe(event => {
  // Handle remote changes
  updateEditor(event);
});

2. Sync Server

Node.js service handling WebSocket connections:

• Connection management and authentication
• Document state synchronization
• Presence broadcasting
• Persistence to PostgreSQL

3. Presence System

Track active users per document:

interface Presence {
  odID: string;
  name: string;
  color: string;
  cursor: { index: number; length: number } | null;
  lastActive: number;
}

4. Conflict Resolution

CRDTs provide automatic conflict resolution:

• Character-level operations merge without conflicts
• Last-writer-wins for metadata
• Tombstones for deletions

Example Usage

User experience:

1. User A opens document, sees their cursor
2. User B opens same document, both see each other's cursors
3. User A types "Hello", User B sees "Hello" appear in real-time
4. User B types " World" at the end, both see "Hello World"
5. Both users type simultaneously at different positions - no conflicts

Alternatives Considered

Alternative 1: Operational Transformation (OT)

Google Docs approach using transformation functions.

Pros:

• Battle-tested at scale
• Smaller message payloads

Cons:

• Complex to implement correctly
• Requires central server for ordering
• Harder to add new operation types
• Doesn't support offline well

Why not chosen: CRDTs are simpler to implement, naturally support offline, and Yjs provides a mature implementation.

Alternative 2: Lock-Based Editing

Only one user can edit at a time.

Pros:

• Simple to implement
• No conflict resolution needed

Cons:

• Poor user experience
• Doesn't scale for teams
• Not competitive with market

Why not chosen: Doesn't meet user expectations or competitive requirements.

Alternative 3: Firebase Realtime Database

Use Firebase for sync layer.

Pros:

• Quick to implement
• Managed service

Cons:

• Vendor lock-in
• Less control over data
• Higher cost at scale
• Doesn't integrate with existing auth

Why not chosen: Strategic preference for self-hosted solutions and cost concerns at our scale.

Implementation Plan

Phases

Phase 1: Foundation (3 weeks)

• Set up Yjs integration with draft-js
• Deploy sync server (single instance)
• Implement basic real-time sync
• Add presence indicators
• Internal testing

Phase 2: Production Readiness (2 weeks)

• Horizontal scaling for sync servers
• Redis pub/sub for cross-instance sync
• Persistence layer integration
• Performance optimization
• Load testing

Phase 3: Rollout (2 weeks)

• Beta with 10% of users
• Monitor and fix issues
• Gradual rollout to 100%
• Documentation and training

Dependencies

• Infrastructure: Need 3 additional server instances
• Redis: Pub/sub enabled (already available)
• Frontend: draft-js upgrade to v0.12

Rollout Strategy

Feature flag controlled rollout:

1. Week 1: Internal team only
2. Week 2: Beta users (opt-in)
3. Week 3: 10% of users
4. Week 4: 50% of users
5. Week 5: 100% of users

Rollback: Disable feature flag, fall back to REST-based saving

Risks and Mitigations

Success Metrics

• Adoption: 80% of collaborative documents use real-time editing within 3 months
• Performance: < 100ms latency for sync operations (p95)
• Reliability: 99.9% sync success rate
• User satisfaction: NPS increase of 10 points
• Support tickets: 50% reduction in collaboration-related tickets

Open Questions

• Which CRDT library to use? Resolved: Yjs
• Max users per document? Resolved: 50 concurrent
• How to handle very large documents (>1MB)?
• Should we show typing indicators in addition to cursors?

References

• Yjs Documentation
• CRDT Research Paper
• Figma's Multiplayer Technology
• Internal Doc: WebSocket Infrastructure
• Related RFCs:
  • RFC-2025-038: WebSocket Infrastructure
  • RFC-2024-089: Document Storage Redesign

Feedback

Reviewers

Discussion Summary

Performance on mobile (Lisa): Concerns about battery and data usage. Mitigation: Implement throttling for mobile clients, batch updates every 500ms instead of real-time.

Redis scaling (James): Question about Redis cluster mode. Answer: Using Redis Cluster with 3 nodes, pub/sub will use channel-based routing.

## RFC Process Best Practices

### 1. States and Lifecycle

Draft → In Review → [Accepted | Rejected | Withdrawn] ↓ Superseded (by newer RFC)

### 2. Review Process

**Week 1: Draft**
- Author writes initial RFC
- Informal feedback from close collaborators
- Share in team channel for early input

**Week 2: Formal Review**
- RFC status → "In Review"
- Assign reviewers (2-4 people)
- Set review deadline
- Async comments via RFC document

**Week 3: Resolution**
- Address feedback
- Hold sync meeting if needed
- Update status to Accepted/Rejected

### 3. Who Should Review?

- Technical experts in affected areas
- Representatives from impacted teams
- Security/privacy reviewers (if applicable)
- Senior engineers or architects

### 4. Maintaining RFCs

docs/ rfcs/ RFC-2025-042-realtime-collab.md RFC-2025-041-auth-redesign.md README.md # Index with status PROCESS.md # How to write/review RFCs

### 5. RFC vs ADR

| Aspect | RFC | ADR |
|--------|-----|-----|
| Timing | Before decision | After decision |
| Purpose | Gather feedback | Document decision |
| Format | Detailed proposal | Concise record |
| Discussion | Expected | Minimal |
| Length | 5-20 pages | 1-3 pages |

Use RFCs for proposals, then create an ADR summarizing the final decision.

## Common Mistakes

### 1. Too Much Detail Too Early
**Bad:** Full implementation spec in draft
**Good:** High-level design, iterate based on feedback

### 2. No Clear Problem Statement
**Bad:** "We should use Kubernetes"
**Good:** "Our deployment takes 2 hours and fails 30% of the time..."

### 3. Missing Alternatives
**Bad:** Only presenting your preferred solution
**Good:** Genuine exploration of options with trade-offs

### 4. Ignoring Non-Goals
**Bad:** Scope creep during review
**Good:** Clear boundaries on what's out of scope

### 5. No Success Metrics
**Bad:** "This will make things better"
**Good:** "Reduce deployment time from 2 hours to 15 minutes"

---

*RFCs transform "let's just build it" into "let's build the right thing." The upfront investment in design and discussion pays dividends in avoided rework and team alignment.*