Commenting & Discussion System Documentation¶

Last Updated: January 9, 2026 Status: Fully Implemented

Overview¶

The commenting and discussion system provides forum-like discussions for corpuses, document-level discussions, and a global discussions view with @ mentions support. This document serves as a reference for the implemented system architecture.

Quick Status Summary¶

Implementation Status¶

Architecture Overview¶

High-Level Architecture¶

Application Layer
  - Corpus Detail (Corpuses.tsx)
  - Document Viewer (DocumentKnowledgeBase)
  - Global Forum View (/discussions)
           |
Thread Components Layer
  - ThreadList, ThreadDetail, ThreadSearch
  - MessageItem, MessageTree, VoteButtons
  - ModerationControls, NotificationBell
           |
State Management Layer
  - Jotai Atoms (threadAtoms.ts)
  - Apollo Cache
           |
Data Layer
  - GraphQL API (queries & mutations)
  - Backend Django + GraphQL (conversation models)

Technology Stack¶

• State Management: Jotai (atomic state) - see frontend/src/atoms/threadAtoms.ts
• GraphQL Client: Apollo Client
• Styling: styled-components
• Routing: React Router
• Testing: Playwright Component Tests
• Rich Text: TipTap (message composer)
• Icons: Lucide React

Source File Locations¶

Backend¶

Frontend Components¶

Notification Components¶

Badge Components¶

Mention Components¶

Routes and Views¶

State Management¶

Tests¶

State Management¶

Jotai Atoms¶

The discussion system uses Jotai atoms defined in frontend/src/atoms/threadAtoms.ts:

• threadSortAtom - Current sort order (newest, active, upvoted, pinned)
• threadFiltersAtom - Filter options (showLocked, showDeleted)
• currentThreadIdAtom - Currently selected thread
• selectedMessageIdAtom - Message for deep linking
• expandedMessageIdsAtom - Collapsible thread state
• showCreateThreadModalAtom - Thread creation modal visibility
• replyingToMessageIdAtom - Reply form target

Apollo Cache Configuration¶

Cache policies for conversation types are configured in the Apollo cache setup. Key considerations:

• ConversationType.allMessages - Messages are in-memory only, not paginated
• ChatMessageType.upvoteCount/downvoteCount - Use optimistic updates
• Query.conversations - Paginated with cursor-based merging

Routing¶

Routes¶

Navigation Utilities¶

Thread navigation utilities are available in frontend/src/utils/navigationUtils.ts for: - Updating thread selection in URL - Generating corpus thread URLs - Navigating between thread views

Key Features¶

@ Mentions System¶

The @ mention system allows users to reference corpuses, documents, and other users in messages.

Backend Implementation: - Permission-based filtering (write access OR public resources) - GraphQL search queries: searchCorpusesForMention, searchDocumentsForMention - IDOR protection via silent filtering

Frontend Implementation: - TipTap extension with @ trigger - Autocomplete dropdown with keyboard navigation - Clickable mention chips for navigation

Documentation: See docs/permissioning/mention_permissioning_spec.md for detailed permissioning rules.

Voting System¶

• Upvote/downvote with optimistic updates
• Vote counts displayed on messages
• User's current vote state tracked

Moderation¶

• Pin/unpin threads
• Lock/unlock threads
• Soft delete/restore threads and messages
• Moderator badge display

Notifications¶

• Real-time notification polling (30-second interval)
• Unread count badge
• Notification types: replies, mentions, badge awards, moderation actions
• Mark as read/unread functionality

Badge Celebrations¶

• Toast notifications for badge awards
• Full-screen celebration modal for significant badges
• Queue management for multiple simultaneous badges
• Framer Motion animations

Conversation Types¶

The backend supports flexible conversation types:

The conversation_type field is a UI hint - the backend doesn't enforce strict behavior differences. Frontend adapts UI based on context.

Security Patterns¶

IDOR Prevention¶

All mutations use visible_to_user() filtering or creator-scoped queries BEFORE object retrieval. Uniform error messages prevent resource enumeration.

Example pattern:

try:
    obj = Model.objects.visible_to_user(user).get(pk=pk)
except Model.DoesNotExist:
    return Mutation(ok=False, message="Not found")  # Same for non-existent AND unauthorized

Permission Model¶

• Conversations inherit permissions from parent corpus/document
• Mentions require write permission on private resources OR resource must be public
• Moderation requires corpus/document ownership or explicit moderator role

Testing¶

Running Tests¶

# Backend conversation tests
docker compose -f test.yml run django pytest opencontractserver/tests/test_mention_permissions.py -v

# Frontend component tests
cd frontend
yarn test:ct --reporter=list -g "Thread"
yarn test:ct --reporter=list frontend/src/components/threads/__tests__/

Test Patterns¶

• Use test wrappers that provide MockedProvider + JotaiProvider
• GraphQL mocks must match variables exactly (null vs undefined matters)
• Include mocks for refetch calls
• Use --reporter=list to prevent Playwright hanging

Performance Considerations¶

1. Message Tree Memoization - Use useMemo for tree building
2. Virtual Scrolling - For lists with >100 items
3. Debounced Search - 300ms debounce on search inputs
4. Lazy Loading - Images and avatars use loading="lazy"
5. Polling Intervals - 30-second polling for notifications and thread updates

Accessibility¶

• Keyboard navigation through thread lists (Tab, Enter, Arrow keys)
• ARIA labels on interactive elements
• Focus management for modals
• Screen reader announcements for loading/error states
• WCAG 2.1 AA compliance

Related Documentation¶

• Permissioning Guide: docs/permissioning/consolidated_permissioning_guide.md
• Mention Permissions: docs/permissioning/mention_permissioning_spec.md
• Frontend Routing: docs/frontend/routing_system.md
• PDF Data Layer: docs/architecture/PDF-data-layer.md

Historical Implementation Notes¶

The discussion system was implemented across multiple issues: