User Story

As a document collaborator
I want to add and reply to comments in shared documents in real-time
So that I can discuss content with teammates without leaving the document or losing context

Acceptance Criteria

Scenario 1: Add New Comment (Happy Path)

Given I am viewing a shared document with edit permissions
And I am logged in
When I highlight a section of text
And I click the “Add Comment” button
And I type my comment text
And I click “Post Comment”
Then the comment is created immediately
And the comment appears anchored to the selected text
And the highlighted text shows a visual indicator (e.g., background color)
And all other users viewing the document see the comment within 2 seconds

Scenario 2: Reply to Existing Comment (Happy Path)

Given I am viewing a document with existing comments
And I have at least view permissions
When I click on a comment thread
And I type a reply in the reply field
And I click “Reply”
Then my reply is posted immediately
And my reply appears beneath the parent comment
And all other users viewing the comment thread see the reply within 2 seconds
And the comment thread expands to show the new reply

Scenario 3: Real-Time Comment Notification

Given User A and User B are both viewing the same document
When User A adds a new comment
Then User B sees a notification badge indicating a new comment within 2 seconds
And User B sees the comment appear in the document without page refresh
And the new comment indicator is visually distinct

Scenario 4: Comment Validation - Empty Comment

Given I am adding a new comment
When I leave the comment text field empty
And I click “Post Comment”
Then the comment is not posted
And I see an inline error “Comment cannot be empty”
And the comment form remains open with focus on the text field

Scenario 5: Comment Validation - Text Length Limit

Given I am composing a comment
When I enter text exceeding the maximum allowed length (e.g., 5000 characters)
Then I see a character counter showing remaining characters
And the “Post Comment” button is disabled when limit is exceeded
And I see a warning “Comment exceeds maximum length (5000 characters)”

Scenario 6: Concurrent Comment Creation - Same Text Selection

Given User A and User B both have the same text highlighted
When User A creates a comment on the selection
And User B creates a comment on the same selection within 2 seconds
Then both comments are created successfully
And both comments appear anchored to the same text
And both users see both comments in the comment thread
And comments are ordered by timestamp (oldest first)

Scenario 7: Concurrent Reply Conflict - Same Parent Comment

Given User A and User B are both viewing the same comment thread
When User A posts a reply at the same time as User B
Then both replies are created successfully
And both replies appear in the comment thread
And replies are ordered chronologically
And each user sees both replies appear in real-time

Scenario 8: Edit Comment - Optimistic Locking

Given I have posted a comment
And the comment has not been modified by anyone else
When I click “Edit” on my comment
And I modify the text
And I click “Save”
Then the comment is updated successfully
And the edit timestamp is displayed (“Edited [time ago]”)
And all other users see the updated comment within 2 seconds

Scenario 9: Edit Conflict Detection - Concurrent Edit

Given User A and User B are both viewing User A’s comment
When User A starts editing the comment
And User B also edits the same comment before User A saves
And User A clicks “Save” first
And User B clicks “Save” second
Then User A’s edit is saved successfully
And User B sees a conflict warning “This comment was edited by [User A]. Please review changes.”
And User B sees a diff view showing User A’s changes
And User B can choose to “Keep my version” or “Discard my changes”

Scenario 10: Delete Comment - Pessimistic Lock Check

Given User A is the author of a comment
When User A clicks “Delete” on their comment
And the comment has replies from other users
Then User A sees a confirmation dialog “This comment has [N] replies. Delete entire thread?”
And User A can choose “Delete Thread” or “Cancel”
And if confirmed, the comment and all replies are deleted
And all other users see the comment thread removed within 2 seconds

Scenario 11: Delete Comment - Concurrent Delete and Reply Race Condition

Given User A is viewing a comment thread
And User B is the comment author
When User A starts typing a reply
And User B deletes the parent comment before User A posts
And User A clicks “Reply”
Then the reply fails gracefully
And User A sees error “This comment has been deleted and can no longer be replied to”
And User A’s reply text is preserved in the form
And User A has option to “Copy my text” before closing

Scenario 12: Real-Time Presence Indicators

Given multiple users are viewing the same document
When I view the document
Then I see avatars/indicators of other active users
And I see a live count of users currently viewing
And when users join/leave, the presence list updates within 3 seconds

Scenario 13: Real-Time Typing Indicator

Given User A and User B are viewing the same comment thread
When User A starts typing a reply
Then User B sees an indicator “[User A] is typing…” within 1 second
And the indicator disappears when User A stops typing for 3 seconds
And the indicator disappears when User A posts the reply

Scenario 14: Network Disconnection - Offline Comment Draft

Given I am composing a comment
When my network connection is lost
And I click “Post Comment”
Then I see a status indicator “Connection lost - comment will post when online”
And my comment is queued locally
And when connection is restored, the comment posts automatically
And I see confirmation “Comment posted successfully”

Scenario 15: Network Reconnection - State Synchronization

Given I was offline for 5 minutes while viewing a document
And other users added 3 new comments during that time
When my connection is restored
Then I see a notification “Syncing latest changes…”
And all new comments appear in the document within 5 seconds
And comment threads are updated with correct ordering
And no duplicate comments are shown

Scenario 16: Out-of-Sync State Recovery - Version Mismatch

Given my client is showing an outdated version of a comment thread
When I attempt to reply to the thread
And the system detects a version mismatch
Then the system fetches the latest version of the thread
And I see a message “Loading latest comments…”
And my reply form is preserved
And once synced, I can post my reply

Scenario 17: Stale Comment Thread - Auto-Refresh

Given I have been viewing a comment thread for 10 minutes without interaction
When another user adds a reply to that thread
Then the thread automatically refreshes to show the new reply
And I see a subtle animation indicating new content
And my scroll position is preserved unless the new reply is visible

Scenario 18: Resolve Comment Thread

Given I am the document owner or comment author
And a comment thread discussion is complete
When I click “Resolve” on the comment thread
Then the comment thread is marked as resolved
And the visual highlight on the text changes to a dimmed state
And all users see the resolved status update within 2 seconds
And the comment thread is moved to a “Resolved” section

Scenario 19: Concurrent Resolve Conflict

Given User A and User B both have permission to resolve comments
When User A clicks “Resolve” on a comment thread
And User B clicks “Unresolve” on the same thread simultaneously
Then the last action wins (based on server timestamp)
And both users see the final resolved state
And a notification appears “Status updated by [User]”

Scenario 20: Reopen Resolved Comment

Given I am viewing a resolved comment thread
When I click “Reopen”
Then the comment thread is marked as active again
And the text highlight returns to the active state
And the thread moves back to the “Active Comments” section
And all users see the status change within 2 seconds

Scenario 21: Comment Permissions - Read-Only User

Given I have read-only permissions on a document
When I view the document with existing comments
Then I can see all comment threads
And I cannot see “Add Comment” buttons
And I cannot reply to existing comments
And I see a message “You have read-only access” when hovering over comment areas

Scenario 22: Comment Permissions - Comment-Only User

Given I have comment-only permissions (cannot edit document text)
When I view the document
Then I can add new comments
And I can reply to existing comments
And I can only edit/delete my own comments
And I cannot edit the document text

Scenario 23: Server Error During Comment Post

Given I am posting a comment
When the server returns a 500 error
Then I see error message “Failed to post comment. Please try again.”
And my comment text is preserved in the form
And I see a “Retry” button
And the comment is not posted

Scenario 24: API Timeout During Comment Fetch

Given I am loading a document with many comments
When the API request times out after 30 seconds
Then I see error “Unable to load comments. Please refresh the page.”
And the document text is still visible
And I have option to “Retry loading comments”

Scenario 25: Loading State for Comments

Given I am opening a document with 50+ comments
When the comments are loading
Then I see skeleton loaders where comment threads will appear
And the document text is visible immediately
And comments appear progressively as they load
And I see a progress indicator “Loading comments… [X of Y loaded]”

Scenario 26: Empty State - No Comments Yet

Given I am viewing a document with no comments
When the document loads
Then I see a message “No comments yet. Highlight text to add the first comment.”
And I see visual affordances showing where to click to add comments

Scenario 27: Mention User in Comment

Given I am composing a comment or reply
When I type “@” followed by a name
Then I see an autocomplete dropdown of users with access to the document
And I can select a user from the dropdown
And the mentioned user receives a notification
And the mention is highlighted in the comment (e.g., blue text)

Scenario 28: Special Characters in Comment

Given I am composing a comment
When I include special characters (e.g., <, >, &, emojis, Unicode)
And I post the comment
Then all special characters are properly escaped and displayed
And no XSS vulnerabilities are introduced
And the comment renders correctly for all users

Scenario 29: Comment Anchoring - Text Modification

Given a comment is anchored to specific text
When another user modifies or deletes the anchored text
Then the comment remains visible
And the comment shows a warning “Original text has changed”
And I can view the original text the comment was anchored to
And the comment can be manually re-anchored or marked orphaned

Scenario 30: Bulk Comment Operations

Given I am the document owner
And there are multiple resolved comments
When I select “Clear all resolved comments”
Then I see a confirmation “Delete [N] resolved comments?”
And if confirmed, all resolved comments are deleted
And all users see the comments removed
And the action is logged in the document history

Non-Functional Requirements

Performance

Comment creation/reply posted within 500ms
Real-time updates delivered to all clients within 2 seconds
Comment threads load within 3 seconds for documents with up to 500 comments
Typing indicators appear within 1 second
WebSocket reconnection within 5 seconds of network restoration

Security

All comment content sanitized to prevent XSS attacks
Comments encrypted in transit (TLS 1.3+)
User authentication required for all comment operations
Rate limiting: max 60 comments per user per minute
Audit log for all comment create/edit/delete operations

Accessibility

Full keyboard navigation support (Tab, Enter, Esc)
Screen reader announces new comments and replies
ARIA live regions for real-time updates
High contrast mode support for comment highlights
Focus management when opening/closing comment threads

Browser Compatibility

Modern browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
WebSocket support required (fallback to long-polling if unavailable)

Data Integrity

Comment transactions are atomic (all-or-nothing)
Optimistic locking prevents concurrent edit conflicts
Version numbers track comment revisions
Deleted comments are soft-deleted for 30 days (audit trail)

Concurrency

Locking Strategy: Optimistic locking for comment edits (version-based conflict detection)
Conflict Resolution: Last-write-wins for resolve/unresolve; user-prompted merge for concurrent edits
State Synchronization: Eventually consistent with automatic sync every 30 seconds or on focus
Real-Time Protocol: WebSocket with automatic reconnection and queue replay

Edge Cases to Consider

User deletes their account while comments exist - handle orphaned comments
Maximum nesting depth for reply threads (e.g., 5 levels) to prevent infinite nesting
Comment anchored to text that spans multiple pages or sections
User loses permission while composing a comment
Document is deleted while users are commenting
Extremely long comment threads (100+ replies) - pagination or lazy loading
User edits text that has 10+ comments attached - how to preserve all anchors
Multiple users @mention the same person simultaneously
Comment includes a link to another comment (circular reference)
User views document on mobile with limited screen space for comment threads

Definition of Done

Users can add comments to selected text in real-time
Users can reply to comment threads in real-time
All users see new comments/replies within 2 seconds
Real-time presence indicators show active users
Typing indicators appear when users are composing
Comment text is validated (not empty, length limit)
Concurrent edit conflicts detected and resolved gracefully
Concurrent delete/reply race conditions handled
Optimistic locking prevents lost updates
Offline comment drafts queued and posted on reconnect
Network interruptions handled with auto-sync
Version mismatch detection and recovery
Permission-based access control (read-only, comment-only, edit)
Server errors and timeouts handled gracefully
Comment threads can be resolved/reopened
Comments remain anchored even if text is modified
@mentions send notifications to mentioned users
Special characters and emojis render correctly
All comment operations logged for audit trail
Unit tests for all validation and conflict resolution logic
Integration tests for real-time synchronization scenarios
Load testing for 100+ concurrent users
Accessibility review passed (WCAG 2.1 AA)
Security review passed (XSS, injection prevention)

Technical Notes

Suggested Implementation:

Backend: WebSocket server for real-time updates (e.g., Phoenix Channels, Socket.io)
Optimistic Locking: Use version numbers or timestamps for conflict detection
State Management: Client-side store with automatic sync (e.g., Redux, Vuex, or Phoenix LiveView)
Presence Tracking: Use Presence API (e.g., Phoenix Presence) for live user list
Typing Indicators: Debounced WebSocket events (throttle to 1 per second)
Offline Queue: IndexedDB or localStorage for pending comments
API Endpoints (if REST-based):
- POST /api/documents/:id/comments - Create comment
- POST /api/comments/:id/replies - Reply to comment
- PATCH /api/comments/:id - Edit comment (includes version check)
- DELETE /api/comments/:id - Delete comment
- PATCH /api/comments/:id/resolve - Resolve/unresolve thread
- GET /api/documents/:id/comments - Fetch all comments
Processing Considerations:
- Index comments by document_id and anchor position for fast retrieval
- Soft-delete comments to preserve thread integrity
- Consider eventual consistency for presence/typing indicators (acceptable lag)
- Implement rate limiting per user to prevent spam

Real-Time Document Commenting System

Input

Output