Comments on a Resource

PATTERN: Comments on a Resource
INPUT: resource_id, comment_text, parent_comment_id (optional, for replies)
OUTPUT: comment_record (with author, timestamp, edited_at)

STEPS:
  1. User views the resource with existing comments listed below
  2. User clicks comment box, types text
  3. IF user is not signed in → prompt to sign in (don't lose their text)
  4. Validate text (not empty, not over max length, not spam-like)
  5. Optimistically render the new comment with "sending..." state
  6. Send to server (resource_id, text, optional parent_id)
  7. Server validates permissions (can user comment on this resource?)
  8. Persist comment with author_id and timestamp
  9. Return success + actual comment record
  10. Replace optimistic UI with confirmed comment
  11. Notify mentioned users and resource owner (async)

ERROR_HANDLING:
  - Server rejects (rate limit, spam) → show clear reason, keep text in box for editing
  - Network failure → keep optimistic state with "Failed, retry?" overlay
  - User edits comment → re-validate, update with edited_at timestamp, show "(edited)" badge
  - User deletes own comment → soft-delete (replace with "Comment deleted" placeholder if it has replies)
  - Comment too long → show character counter as user types, disable submit at limit

EXTENSION_POINTS:
  - @mention specific users (composable_with: ["mention"])
  - Moderation queue for flagged comments (composable_with: ["moderation"])
  - Email/push notification on new comments (composable_with: ["notification"])
  - Real-time updates so other viewers see comments appear (composable_with: ["realtime-share"])

• What if a user comments on a resource that's then deleted?

  medium

  Orphaned comments could cause errors when fetching.

  Suggested handling: Cascade-delete OR soft-delete the parent and keep comments accessible from a "your activity" view. Decide based on product.

• What if two users post a comment at the exact same time?

  low

  Race condition in optimistic UI ordering.

  Suggested handling: Use server-assigned timestamp as source of truth. After confirmation, re-sort comments. Tiny visual flicker is acceptable.

• What if comments contain spam or abusive content?

  high

  Without moderation, your platform becomes unusable.

  Suggested handling: Add a "Report" button on every comment. Use automated spam detection (e.g., Akismet or LLM classification) for first-pass. Compose with `moderation` pattern for human review queue.

• What if a user edits a comment after others have replied?

  medium

  Could change context, making replies confusing or misleading.

  Suggested handling: Show "(edited)" badge on edited comments. Optionally show edit history on click. For high-stakes platforms (forums, moderation), consider locking edits after first reply.

• What if there are thousands of comments on one resource?

  high

  Loading all at once is slow and crashes mobile.

  Suggested handling: Paginate (load most recent 20, "show more"). For threaded views, collapse old threads. Use cursor-based pagination, not offset (faster, no duplicates).