Requirements Document

Introduction

BrightHub is a Twitter-like social network module for the BrightChain ecosystem. It provides decentralized social networking capabilities including posts, threads, replies, likes, reposts, follows, and rich text formatting with markdown, emojis, and FontAwesome icons. The module integrates with the existing BrightChain blockchain/database infrastructure and follows the established Nx monorepo patterns.

Glossary

BrightHub_System: The complete social network module encompassing all libraries, services, and components
Post_Service: Backend service handling post creation, retrieval, and management
Thread_Service: Backend service managing threaded conversations and replies
User_Profile_Service: Backend service managing user profiles and social connections
Feed_Service: Backend service generating personalized and public feeds
Connection_Service: Backend service managing connection lists, categories, and relationship features
Discovery_Service: Backend service providing connection recommendations and suggestions
Text_Formatter: Service that processes markdown, emojis, and FontAwesome icons in post content
Post: A single social media message with optional media attachments
Thread: A hierarchical conversation consisting of a root post and its replies
Reply: A post that responds to another post within a thread
Repost: Sharing another user’s post to one’s own followers
Quote_Post: A repost that includes additional commentary
Like: An endorsement action on a post
Follow: A subscription relationship between users
Connection: A follow relationship with additional metadata (category, notes, priority)
Connection_List: A user-created grouping of connections for organization and filtering
Connection_Category: A predefined or custom classification for connections (close friends, professional, etc.)
Hub: A private group of connections who can see exclusive content
Priority_Connection: A connection whose posts are always shown first in timeline
Quiet_Mode: A connection setting that shows posts but suppresses notifications
Connection_Note: A private note attached to a connection visible only to the note creator
Connection_Strength: A calculated metric based on interaction frequency between users
Mutual_Connection: A user who is followed by both the current user and another user
Messaging_Service: Backend service handling direct messages, conversations, and message requests
Conversation: A direct message thread between two or more users
Direct_Message: A private message sent between users within a conversation
Group_Conversation: A conversation with three or more participants
Message_Request: A pending message from a non-follower awaiting acceptance
Message_Reaction: An emoji reaction attached to a specific message
Read_Receipt: An indicator showing when a message was seen by recipients
Typing_Indicator: A real-time signal showing when a user is composing a message
Message_Thread: A reply chain within a conversation responding to a specific message
Conversation_Archive: A hidden conversation that can be restored later
Pinned_Conversation: A conversation marked for quick access at the top of the inbox
Timeline: A chronological feed of posts from followed users
Mention: A reference to another user using @username syntax
Hashtag: A topic tag using #topic syntax
Notification_Provider: React context provider that manages notification state and subscriptions across the application
Notification_Service: Backend service handling notification creation, delivery, and management
Notification_Bell: UI component in TopMenu displaying notification icon with unread badge
Notification_Dropdown: UI panel showing recent notifications when bell is clicked
Notification_Category: Classification of notifications (social, messages, connections, system)
Notification_Preferences: User settings controlling notification delivery by category and channel
Notification_Channel: Delivery method for notifications (in-app, email, push)
Notification_Group: Aggregated notifications of the same type (e.g., “5 people liked your post”)
Quiet_Hours: Time period during which notifications are suppressed
Do_Not_Disturb: Mode that suppresses all non-critical notifications
Post_DTO: Data Transfer Object for posts between frontend and backend
**IBasePostData**: Generic interface for post data supporting different ID types
**IBaseConnectionList**: Generic interface for connection list data
**IBaseConnectionCategory**: Generic interface for connection category data
**IBaseHub**: Generic interface for hub/close friends data

Requirements

Requirement 1: Post Creation and Management

User Story: As a user, I want to create, edit, and delete posts, so that I can share content with my followers.

Acceptance Criteria

WHEN a user submits valid post content, THE Post_Service SHALL create a new post and return the Post_DTO
WHEN a user submits post content exceeding 280 characters, THE Post_Service SHALL reject the request with a validation error
WHEN a user submits empty post content, THE Post_Service SHALL reject the request with a validation error
WHEN a user requests to edit their own post within 15 minutes of creation, THE Post_Service SHALL update the post content and mark it as edited
WHEN a user requests to edit a post older than 15 minutes, THE Post_Service SHALL reject the request with a time limit error
WHEN a user requests to delete their own post, THE Post_Service SHALL soft-delete the post and cascade to associated interactions
IF a user attempts to edit or delete another user’s post, THEN THE Post_Service SHALL reject the request with an authorization error
THE Post_Service SHALL store posts in the brightchain-db threading database

Requirement 2: Thread and Reply Management

User Story: As a user, I want to reply to posts and view threaded conversations, so that I can engage in discussions.

Acceptance Criteria

WHEN a user submits a reply to an existing post, THE Thread_Service SHALL create a reply post linked to the parent post
WHEN a user requests a thread view, THE Thread_Service SHALL return the root post and all nested replies in hierarchical order
THE Thread_Service SHALL support reply nesting up to 10 levels deep
WHEN a reply exceeds the maximum nesting depth, THE Thread_Service SHALL attach the reply to the deepest allowed parent
WHEN a parent post is deleted, THE Thread_Service SHALL preserve replies with a “parent deleted” indicator
THE Thread_Service SHALL track reply counts for each post

User Story: As a user, I want to like, repost, and quote posts, so that I can engage with and share content.

Acceptance Criteria

WHEN a user likes a post, THE Post_Service SHALL record the like and increment the post’s like count
WHEN a user unlikes a post, THE Post_Service SHALL remove the like and decrement the post’s like count
WHEN a user reposts a post, THE Post_Service SHALL create a repost entry visible to the user’s followers
WHEN a user creates a quote post, THE Post_Service SHALL create a new post containing the quoted post reference and user commentary
THE Post_Service SHALL prevent duplicate likes from the same user on the same post
THE Post_Service SHALL prevent duplicate reposts from the same user of the same post
WHEN a user requests their interaction status on a post, THE Post_Service SHALL return whether the user has liked and/or reposted the post

Requirement 4: User Following System

User Story: As a user, I want to follow and unfollow other users, so that I can curate my timeline.

Acceptance Criteria

WHEN a user follows another user, THE User_Profile_Service SHALL create a follow relationship and update follower/following counts
WHEN a user unfollows another user, THE User_Profile_Service SHALL remove the follow relationship and update counts
THE User_Profile_Service SHALL prevent users from following themselves
WHEN a user requests their followers list, THE User_Profile_Service SHALL return a paginated list of follower profiles
WHEN a user requests their following list, THE User_Profile_Service SHALL return a paginated list of followed user profiles
THE User_Profile_Service SHALL support pagination with cursor-based navigation for follower/following lists
WHEN a user enables approve followers mode, THE User_Profile_Service SHALL require approval for new follow requests
WHEN a follow request is received for a protected account, THE User_Profile_Service SHALL create a pending request with optional custom message
WHEN a user approves a follow request, THE User_Profile_Service SHALL create the follow relationship and notify the requester
WHEN a user rejects a follow request, THE User_Profile_Service SHALL delete the request and optionally notify the requester
THE User_Profile_Service SHALL support granular approve mode (approve all, approve from mutuals only, approve none)

Requirement 5: Timeline and Feed Generation

User Story: As a user, I want to view my personalized timeline and explore public content, so that I can discover and consume content.

Acceptance Criteria

WHEN a user requests their home timeline, THE Feed_Service SHALL return posts from followed users in reverse chronological order
WHEN a user requests the public timeline, THE Feed_Service SHALL return recent public posts from all users
THE Feed_Service SHALL support cursor-based pagination for all timeline requests
THE Feed_Service SHALL include reposts and quote posts in timeline results
WHEN a user requests a specific user’s profile feed, THE Feed_Service SHALL return that user’s posts and reposts
THE Feed_Service SHALL exclude posts from blocked users in timeline results
THE Feed_Service SHALL return a maximum of 50 posts per timeline request
WHEN a user requests timeline filtered by connection list, THE Feed_Service SHALL return only posts from list members
WHEN a user requests timeline filtered by connection category, THE Feed_Service SHALL return only posts from categorized connections
THE Feed_Service SHALL display posts from priority connections before other posts in the timeline
THE Feed_Service SHALL include hub-restricted posts when the requesting user is a hub member
WHEN a user has active temporary mutes, THE Feed_Service SHALL exclude muted users’ posts from timeline

Requirement 6: Rich Text Formatting

User Story: As a user, I want to format my posts with markdown, emojis, and icons, so that I can create expressive content.

Acceptance Criteria

WHEN post content contains markdown syntax, THE Text_Formatter SHALL parse and render the markdown to HTML
WHEN post content contains emoji shortcodes, THE Text_Formatter SHALL convert shortcodes to Unicode emoji characters
WHEN post content contains FontAwesome icon syntax, THE Text_Formatter SHALL render the appropriate icon elements
THE Text_Formatter SHALL sanitize HTML output to prevent XSS attacks
THE Text_Formatter SHALL preserve raw content for editing while providing formatted content for display
FOR ALL valid post content, parsing then formatting then extracting raw text SHALL produce equivalent semantic content (round-trip property)

Requirement 7: Mentions and Hashtags

User Story: As a user, I want to mention other users and use hashtags, so that I can reference people and topics.

Acceptance Criteria

WHEN post content contains @username mentions, THE Post_Service SHALL extract and validate mentioned usernames
WHEN a valid mention is detected, THE Post_Service SHALL create a notification for the mentioned user
WHEN post content contains #hashtag tags, THE Post_Service SHALL extract and index hashtags for search
WHEN a user searches for a hashtag, THE Feed_Service SHALL return posts containing that hashtag
THE Post_Service SHALL support up to 10 mentions per post
THE Post_Service SHALL support up to 10 hashtags per post

Requirement 8: User Profile Management

User Story: As a user, I want to manage my profile information, so that others can learn about me.

Acceptance Criteria

WHEN a user updates their display name, THE User_Profile_Service SHALL validate and store the new display name
WHEN a user updates their bio, THE User_Profile_Service SHALL validate the bio does not exceed 160 characters
WHEN a user updates their profile picture, THE User_Profile_Service SHALL validate the image format and store the reference
WHEN a user updates their header image, THE User_Profile_Service SHALL validate the image format and store the reference
THE User_Profile_Service SHALL support profile location and website URL fields
WHEN a user requests another user’s profile, THE User_Profile_Service SHALL return the public profile data including follower/following counts

Requirement 9: Notification System Core

User Story: As a user, I want to receive notifications for interactions, so that I can stay informed about activity on my content.

Acceptance Criteria

WHEN a user’s post receives a like, THE Notification_Service SHALL create a notification for the post author with category “social”
WHEN a user’s post receives a reply, THE Notification_Service SHALL create a notification for the post author with category “social”
WHEN a user is mentioned in a post, THE Notification_Service SHALL create a notification for the mentioned user with category “social”
WHEN a user gains a new follower, THE Notification_Service SHALL create a notification for the followed user with category “connections”
WHEN a user’s post is reposted or quoted, THE Notification_Service SHALL create a notification for the post author with category “social”
WHEN a user requests their notifications, THE Notification_Service SHALL return notifications in reverse chronological order with pagination
THE Notification_Service SHALL support marking notifications as read individually or in bulk
WHEN a user requests notifications filtered by connection list, THE Notification_Service SHALL return only notifications from list members
WHEN a user requests notifications filtered by connection category, THE Notification_Service SHALL return only notifications from categorized connections
WHILE quiet mode is enabled for a connection, THE Notification_Service SHALL suppress notifications from that connection
WHEN a user receives a follow request, THE Notification_Service SHALL create a notification with category “connections” and the optional custom message
WHEN a connection the user hasn’t interacted with in 30 days posts, THE Notification_Service SHALL optionally create a “reconnect” reminder notification with category “connections”
THE Notification_Service SHALL assign each notification to exactly one Notification_Category
THE Notification_Service SHALL store a click-through URL for each notification linking to the relevant content

Requirement 10: Search Functionality

User Story: As a user, I want to search for posts and users, so that I can discover content and people.

Acceptance Criteria

WHEN a user searches with a text query, THE BrightHub_System SHALL return matching posts containing the query terms
WHEN a user searches with a hashtag, THE BrightHub_System SHALL return posts tagged with that hashtag
WHEN a user searches for users, THE BrightHub_System SHALL return user profiles matching the query by username or display name
THE BrightHub_System SHALL support combined search returning both posts and users
THE BrightHub_System SHALL support pagination for all search results

Requirement 11: API Endpoints

User Story: As a developer, I want RESTful API endpoints, so that I can integrate BrightHub with frontend applications.

Acceptance Criteria

THE BrightHub_System SHALL expose POST /api/brighthub/posts for creating posts
THE BrightHub_System SHALL expose GET /api/brighthub/posts/:id for retrieving a single post
THE BrightHub_System SHALL expose DELETE /api/brighthub/posts/:id for deleting posts
THE BrightHub_System SHALL expose POST /api/brighthub/posts/:id/like for liking posts
THE BrightHub_System SHALL expose POST /api/brighthub/posts/:id/repost for reposting
THE BrightHub_System SHALL expose GET /api/brighthub/timeline/home for home timeline
THE BrightHub_System SHALL expose GET /api/brighthub/timeline/public for public timeline
THE BrightHub_System SHALL expose GET /api/brighthub/users/:id for user profiles
THE BrightHub_System SHALL expose POST /api/brighthub/users/:id/follow for following users
THE BrightHub_System SHALL expose GET /api/brighthub/notifications for user notifications
THE BrightHub_System SHALL expose GET /api/brighthub/search for search functionality
THE BrightHub_System SHALL return appropriate HTTP status codes for success and error responses

Requirement 12: React Component Library

User Story: As a frontend developer, I want reusable React components, so that I can build the BrightHub UI efficiently.

Acceptance Criteria

THE brighthub-react-components library SHALL provide a PostCard component for displaying individual posts
THE brighthub-react-components library SHALL provide a PostComposer component for creating new posts
THE brighthub-react-components library SHALL provide a Timeline component for displaying feeds
THE brighthub-react-components library SHALL provide a ThreadView component for displaying threaded conversations
THE brighthub-react-components library SHALL provide a UserProfileCard component for displaying user information
THE brighthub-react-components library SHALL provide a NotificationList component for displaying notifications
THE brighthub-react-components library SHALL provide a SearchResults component for displaying search results
THE brighthub-react-components library SHALL provide a FollowButton component for follow/unfollow actions
THE brighthub-react-components library SHALL provide a LikeButton component for like/unlike actions
THE brighthub-react-components library SHALL provide a RepostButton component for repost actions
All components SHALL support theming through a BrightHubThemeProvider
All components SHALL be accessible and comply with ARIA guidelines
All components SHALL use i18n for all user-facing strings via useI18n hook with tComponent(BrightHubComponentId, key) — no hardcoded display text (see Requirement 61)

Requirement 13: Type System and Interfaces

User Story: As a developer, I want strongly-typed interfaces, so that I can ensure type safety across frontend and backend.

Acceptance Criteria

THE brighthub-lib library SHALL define IBasePostData generic interface for post data
THE brighthub-lib library SHALL define IBaseUserProfile generic interface for user profiles
THE brighthub-lib library SHALL define IBaseThread generic interface for thread data
THE brighthub-lib library SHALL define IBaseNotification generic interface for notifications
THE brighthub-lib library SHALL define IBaseFollow generic interface for follow relationships
THE brighthub-lib library SHALL define IBaseLike generic interface for like interactions
THE brighthub-lib library SHALL define IBaseRepost generic interface for repost interactions
THE brightchain-api-lib library SHALL define API response types extending Express Response with BrightHub data interfaces
All enumerations for post types, notification types, and interaction types SHALL be defined in brighthub-lib

Requirement 14: Database Schema

User Story: As a developer, I want a well-defined database schema, so that I can store and query social network data efficiently.

Acceptance Criteria

THE brightchain-db library SHALL define a posts collection schema with content, author, timestamps, and interaction counts
THE brightchain-db library SHALL define a threads collection schema linking posts in parent-child relationships
THE brightchain-db library SHALL define a follows collection schema for user follow relationships
THE brightchain-db library SHALL define a likes collection schema for post likes
THE brightchain-db library SHALL define a reposts collection schema for repost tracking
THE brightchain-db library SHALL define a notifications collection schema for user notifications
THE brightchain-db library SHALL define appropriate indexes for timeline queries, user lookups, and search operations
All schemas SHALL support the BrightChain block-based storage model

Requirement 15: End-to-End Testing

User Story: As a developer, I want comprehensive E2E tests, so that I can ensure the system works correctly.

Acceptance Criteria

THE brightchain-api-e2e library SHALL include tests for all post CRUD operations
THE brightchain-api-e2e library SHALL include tests for thread and reply operations
THE brightchain-api-e2e library SHALL include tests for like, repost, and quote operations
THE brightchain-api-e2e library SHALL include tests for follow/unfollow operations
THE brightchain-api-e2e library SHALL include tests for timeline generation
THE brightchain-api-e2e library SHALL include tests for notification creation and retrieval
THE brightchain-api-e2e library SHALL include tests for search functionality
THE brightchain-react-e2e library SHALL include Playwright tests for PostComposer component
THE brightchain-react-e2e library SHALL include Playwright tests for Timeline component
THE brightchain-react-e2e library SHALL include Playwright tests for ThreadView component
THE brightchain-react-e2e library SHALL include Playwright tests for user profile interactions
THE brightchain-react-e2e library SHALL include Playwright tests for notification interactions

Requirement 16: Integration with Existing Text Formatting Library

User Story: As a developer, I want to integrate the existing text formatting library, so that I can reuse proven markdown, emoji, and icon handling code.

Acceptance Criteria

THE Text_Formatter SHALL integrate the existing markdown-it based formatting logic
THE Text_Formatter SHALL integrate the existing emoji shortcode conversion logic
THE Text_Formatter SHALL integrate the existing FontAwesome icon rendering logic
THE Text_Formatter SHALL expose a unified API for formatting post content
THE Text_Formatter SHALL be usable in both Node.js (backend) and browser (frontend) environments
FOR ALL formatted content, the Text_Formatter SHALL produce consistent output across Node.js and browser environments

Requirement 17: Media Attachments

User Story: As a user, I want to attach images to my posts, so that I can share visual content.

Acceptance Criteria

WHEN a user attaches images to a post, THE Post_Service SHALL validate image formats (JPEG, PNG, GIF, WebP)
THE Post_Service SHALL support up to 4 image attachments per post
WHEN images are attached, THE Post_Service SHALL store image references in the post data
THE Post_Service SHALL validate that total attachment size does not exceed 20MB per post
IF an invalid image format is attached, THEN THE Post_Service SHALL reject the request with a validation error

Requirement 18: Block and Mute Functionality

User Story: As a user, I want to block and mute other users, so that I can control my experience.

Acceptance Criteria

WHEN a user blocks another user, THE User_Profile_Service SHALL prevent the blocked user from viewing the blocker’s content
WHEN a user blocks another user, THE User_Profile_Service SHALL remove any existing follow relationship
WHEN a user mutes another user, THE Feed_Service SHALL exclude the muted user’s posts from the muting user’s timeline
WHEN a user unmutes another user, THE Feed_Service SHALL restore the unmuted user’s posts to the timeline
THE User_Profile_Service SHALL provide endpoints to list blocked and muted users
THE User_Profile_Service SHALL support unblocking users

Requirement 19: Connection Lists Management

User Story: As a user, I want to create and manage custom connection lists, so that I can organize my connections and filter my experience.

Acceptance Criteria

WHEN a user creates a connection list, THE Connection_Service SHALL create the list with a name, description, and visibility setting
WHEN a user adds a connection to a list, THE Connection_Service SHALL create the list membership and update list counts
WHEN a user removes a connection from a list, THE Connection_Service SHALL remove the membership and update counts
THE Connection_Service SHALL support bulk add operations for adding multiple users to a list in a single request
THE Connection_Service SHALL support bulk remove operations for removing multiple users from a list in a single request
WHEN a user requests their lists, THE Connection_Service SHALL return all lists with member counts
WHEN a user requests list members, THE Connection_Service SHALL return a paginated list of member profiles
THE Connection_Service SHALL support up to 100 custom lists per user
THE Connection_Service SHALL support up to 5000 members per list
WHEN a user deletes a list, THE Connection_Service SHALL remove all memberships and the list itself
THE Connection_Service SHALL support list visibility options: private, followers-only, and public
WHEN a list is public, THE Connection_Service SHALL allow other users to follow the list

Requirement 20: Connection Categories

User Story: As a user, I want to categorize my connections, so that I can quickly identify relationship types.

Acceptance Criteria

THE Connection_Service SHALL provide default categories: Close Friends, Family, Professional, Acquaintances, and Interests
WHEN a user creates a custom category, THE Connection_Service SHALL create the category with name and optional color/icon
WHEN a user assigns a category to a connection, THE Connection_Service SHALL update the connection metadata
THE Connection_Service SHALL support multiple categories per connection
WHEN a user requests connections by category, THE Connection_Service SHALL return a paginated list of matching connections
THE Connection_Service SHALL support up to 20 custom categories per user
WHEN a user deletes a custom category, THE Connection_Service SHALL remove the category assignment from all connections
THE Connection_Service SHALL support bulk category assignment for multiple connections

Requirement 21: Connection Notes

User Story: As a user, I want to add private notes to my connections, so that I can remember context about people I follow.

Acceptance Criteria

WHEN a user adds a note to a connection, THE Connection_Service SHALL store the note visible only to the note creator
WHEN a user updates a connection note, THE Connection_Service SHALL update the stored note content
WHEN a user deletes a connection note, THE Connection_Service SHALL remove the note
THE Connection_Service SHALL support notes up to 500 characters per connection
WHEN a user views a connection’s profile, THE Connection_Service SHALL include the private note if one exists
THE Connection_Service SHALL support searching connections by note content
IF a user unfollows a connection, THEN THE Connection_Service SHALL preserve the note for potential re-follow

Requirement 22: Connection Import and Export

User Story: As a user, I want to import and export my connection lists, so that I can backup and migrate my social graph.

Acceptance Criteria

WHEN a user requests a connection export, THE Connection_Service SHALL generate a JSON file containing all connections with metadata
WHEN a user requests a list export, THE Connection_Service SHALL generate a JSON file containing list members and settings
WHEN a user imports a connection file, THE Connection_Service SHALL validate the format and create follow relationships for valid usernames
WHEN a user imports a list file, THE Connection_Service SHALL create the list and add existing connections as members
THE Connection_Service SHALL support CSV format for simple username-only imports
IF an imported username does not exist, THEN THE Connection_Service SHALL skip the entry and include it in an error report
THE Connection_Service SHALL rate-limit import operations to prevent abuse

Requirement 23: Priority Connections

User Story: As a user, I want to mark certain connections as priority, so that I never miss their posts.

Acceptance Criteria

WHEN a user marks a connection as priority, THE Connection_Service SHALL update the connection priority flag
WHEN a user requests their timeline, THE Feed_Service SHALL display posts from priority connections first
THE Connection_Service SHALL support up to 50 priority connections per user
WHEN a user removes priority status from a connection, THE Connection_Service SHALL update the flag and restore normal timeline ordering
WHEN a user requests their priority connections, THE Connection_Service SHALL return a list of all priority-marked connections
THE Feed_Service SHALL visually distinguish priority connection posts in the timeline

Requirement 24: Quiet Mode for Connections

User Story: As a user, I want to set quiet mode for specific connections, so that I can see their posts without receiving notifications.

Acceptance Criteria

WHEN a user enables quiet mode for a connection, THE Connection_Service SHALL update the connection quiet flag
WHILE quiet mode is enabled for a connection, THE BrightHub_System SHALL suppress all notifications from that connection
WHILE quiet mode is enabled, THE Feed_Service SHALL continue to include the connection’s posts in the timeline
WHEN a user disables quiet mode for a connection, THE BrightHub_System SHALL resume notifications from that connection
WHEN a user requests their quiet connections, THE Connection_Service SHALL return a list of all quiet-mode connections

Requirement 25: Temporary Mute with Auto-Unmute

User Story: As a user, I want to temporarily mute connections with automatic unmute, so that I can take breaks without permanent changes.

Acceptance Criteria

WHEN a user sets a temporary mute, THE Connection_Service SHALL store the mute with an expiration timestamp
THE Connection_Service SHALL support mute durations: 1 hour, 8 hours, 24 hours, 7 days, and 30 days
WHEN a temporary mute expires, THE Connection_Service SHALL automatically remove the mute and restore normal behavior
WHILE a temporary mute is active, THE Feed_Service SHALL exclude the muted connection’s posts from timeline
WHEN a user requests their muted connections, THE Connection_Service SHALL return mute status including expiration times
THE Connection_Service SHALL support converting temporary mutes to permanent mutes
THE Connection_Service SHALL support early unmute before expiration

Requirement 26: Connection Discovery and Suggestions

User Story: As a user, I want to discover new connections based on my network and interests, so that I can grow my social graph.

Acceptance Criteria

WHEN a user requests connection suggestions, THE Discovery_Service SHALL return users based on mutual connections
THE Discovery_Service SHALL calculate suggestion scores based on number of mutual connections
WHEN a user has followed hashtags or interests, THE Discovery_Service SHALL suggest users who frequently post about those topics
THE Discovery_Service SHALL provide “Similar to” suggestions based on a specified user’s followers and following
THE Discovery_Service SHALL exclude already-followed users, blocked users, and muted users from suggestions
THE Discovery_Service SHALL support pagination for suggestion results
WHEN a user dismisses a suggestion, THE Discovery_Service SHALL exclude that user from future suggestions for 30 days
THE Discovery_Service SHALL refresh suggestions daily based on network changes

Requirement 27: Connection Strength Indicators

User Story: As a user, I want to see connection strength indicators, so that I can understand my relationship activity levels.

Acceptance Criteria

THE Discovery_Service SHALL calculate connection strength based on interaction frequency (likes, replies, mentions)
THE Discovery_Service SHALL categorize strength as: Strong, Moderate, Weak, or Dormant
WHEN a user views a connection’s profile, THE Discovery_Service SHALL display the connection strength indicator
THE Discovery_Service SHALL update connection strength calculations weekly
WHEN a user requests connections sorted by strength, THE Connection_Service SHALL return connections ordered by strength score
THE Discovery_Service SHALL factor in recency of interactions when calculating strength

Requirement 28: Mutual Connections Display

User Story: As a user, I want to see mutual connections when viewing profiles, so that I can understand shared social context.

Acceptance Criteria

WHEN a user views another user’s profile, THE Connection_Service SHALL display mutual connections count
WHEN a user requests mutual connections, THE Connection_Service SHALL return a paginated list of users followed by both parties
THE Connection_Service SHALL display up to 3 mutual connection avatars on profile previews
WHEN viewing a non-followed user, THE Connection_Service SHALL highlight mutual connections as social proof
THE Connection_Service SHALL cache mutual connection calculations for performance

Requirement 29: Connection History and Insights

User Story: As a user, I want to see my connection history and interaction insights, so that I can understand my relationships over time.

Acceptance Criteria

WHEN a user views a connection’s profile, THE Connection_Service SHALL display when the follow relationship was created
THE Connection_Service SHALL track and display interaction statistics: total likes given, replies exchanged, mentions
WHEN a user requests “haven’t interacted” connections, THE Connection_Service SHALL return connections with no interactions in 30 days
THE Connection_Service SHALL provide weekly connection activity summaries via notification
WHEN a user requests connection insights, THE Connection_Service SHALL return top interacted connections for the period
THE Connection_Service SHALL support insight periods: 7 days, 30 days, 90 days, and all time

Requirement 30: Hubs and Close Friends Content

User Story: As a user, I want to share content exclusively with specific hubs, so that I can control who sees sensitive posts.

Acceptance Criteria

WHEN a user creates a hub, THE Connection_Service SHALL create the hub with name and member list
WHEN a user adds a connection to a hub, THE Connection_Service SHALL update hub membership
WHEN a user creates a post with hub visibility, THE Post_Service SHALL restrict visibility to hub members only
THE Post_Service SHALL support multiple hub selection for post visibility
WHEN a non-hub member requests a hub-restricted post, THE Post_Service SHALL return a not-found or access-denied response
THE Connection_Service SHALL support a default “Close Friends” hub for quick access
WHEN a user views their timeline, THE Feed_Service SHALL include hub-restricted posts from hubs they belong to
THE Feed_Service SHALL visually indicate hub-restricted posts to the viewer
THE Connection_Service SHALL support up to 10 hubs per user
THE Connection_Service SHALL support up to 150 members per hub

Requirement 31: Granular Privacy Controls

User Story: As a user, I want granular privacy controls for my connections, so that I can manage my visibility precisely.

Acceptance Criteria

WHEN a user configures privacy settings, THE User_Profile_Service SHALL support hiding follower count from public view
WHEN a user configures privacy settings, THE User_Profile_Service SHALL support hiding following count from public view
WHEN a user configures privacy settings, THE User_Profile_Service SHALL support hiding followers list from non-followers
WHEN a user configures privacy settings, THE User_Profile_Service SHALL support hiding following list from non-followers
THE User_Profile_Service SHALL support per-list visibility overrides
WHEN a user enables “approve followers” mode, THE User_Profile_Service SHALL require approval for all new followers
THE User_Profile_Service SHALL support “approve from non-mutuals only” mode for selective approval

Requirement 32: Block and Mute Inheritance for Lists

User Story: As a user, I want block and mute settings to apply to my lists, so that blocked users cannot access my curated content.

Acceptance Criteria

WHEN a user blocks another user, THE Connection_Service SHALL automatically remove the blocked user from all lists owned by the blocker
WHEN a user blocks another user, THE Connection_Service SHALL prevent the blocked user from viewing the blocker’s public lists
WHEN a user blocks another user, THE Connection_Service SHALL prevent the blocked user from following the blocker’s lists
WHEN a user mutes another user, THE Feed_Service SHALL exclude the muted user’s posts from list-filtered timelines
IF a blocked user is added to a list via import, THEN THE Connection_Service SHALL skip the blocked user and report the skip

Requirement 33: Connection List Following

User Story: As a user, I want to follow other users’ public lists, so that I can discover curated content without following individuals.

Acceptance Criteria

WHEN a user follows a public list, THE Connection_Service SHALL create a list subscription
WHEN a user requests a list timeline, THE Feed_Service SHALL return posts from all list members in reverse chronological order
THE Connection_Service SHALL notify list owners when their list gains a new follower
WHEN a list owner updates list membership, THE Connection_Service SHALL reflect changes for all list followers
WHEN a user unfollows a list, THE Connection_Service SHALL remove the subscription
THE Connection_Service SHALL support pagination for followed lists
WHEN a list owner makes a public list private, THE Connection_Service SHALL remove all external subscriptions

Requirement 34: Connection Management API Endpoints

User Story: As a developer, I want API endpoints for connection management features, so that I can build rich connection experiences.

Acceptance Criteria

THE BrightHub_System SHALL expose POST /api/brighthub/lists for creating connection lists
THE BrightHub_System SHALL expose GET /api/brighthub/lists for retrieving user’s lists
THE BrightHub_System SHALL expose PUT /api/brighthub/lists/:id for updating list details
THE BrightHub_System SHALL expose DELETE /api/brighthub/lists/:id for deleting lists
THE BrightHub_System SHALL expose POST /api/brighthub/lists/:id/members for adding members to lists
THE BrightHub_System SHALL expose DELETE /api/brighthub/lists/:id/members for removing members from lists
THE BrightHub_System SHALL expose POST /api/brighthub/lists/:id/members/bulk for bulk member operations
THE BrightHub_System SHALL expose GET /api/brighthub/connections/categories for retrieving categories
THE BrightHub_System SHALL expose POST /api/brighthub/connections/:id/note for adding connection notes
THE BrightHub_System SHALL expose GET /api/brighthub/connections/suggestions for connection suggestions
THE BrightHub_System SHALL expose GET /api/brighthub/connections/mutual/:userId for mutual connections
THE BrightHub_System SHALL expose POST /api/brighthub/connections/:id/priority for setting priority status
THE BrightHub_System SHALL expose POST /api/brighthub/connections/:id/quiet for setting quiet mode
THE BrightHub_System SHALL expose POST /api/brighthub/connections/:id/mute/temporary for temporary mutes
THE BrightHub_System SHALL expose GET /api/brighthub/connections/export for exporting connections
THE BrightHub_System SHALL expose POST /api/brighthub/connections/import for importing connections
THE BrightHub_System SHALL expose POST /api/brighthub/hubs for creating hubs
THE BrightHub_System SHALL expose GET /api/brighthub/hubs for retrieving user’s hubs
THE BrightHub_System SHALL expose GET /api/brighthub/connections/:id/insights for connection insights
THE BrightHub_System SHALL expose GET /api/brighthub/follow-requests for pending follow requests
THE BrightHub_System SHALL expose POST /api/brighthub/follow-requests/:id/approve for approving requests
THE BrightHub_System SHALL expose POST /api/brighthub/follow-requests/:id/reject for rejecting requests

Requirement 35: Connection Management React Components

User Story: As a frontend developer, I want React components for connection management, so that I can build the connection UI efficiently.

Acceptance Criteria

THE brighthub-react-components library SHALL provide a ConnectionListManager component for creating and managing lists
THE brighthub-react-components library SHALL provide a ConnectionListCard component for displaying list previews
THE brighthub-react-components library SHALL provide a ConnectionCategorySelector component for assigning categories
THE brighthub-react-components library SHALL provide a ConnectionNoteEditor component for adding/editing notes
THE brighthub-react-components library SHALL provide a ConnectionSuggestions component for displaying suggestions
THE brighthub-react-components library SHALL provide a MutualConnections component for displaying mutual connections
THE brighthub-react-components library SHALL provide a ConnectionStrengthIndicator component for displaying strength
THE brighthub-react-components library SHALL provide a HubManager component for managing hubs
THE brighthub-react-components library SHALL provide a HubSelector component for post visibility selection
THE brighthub-react-components library SHALL provide a FollowRequestList component for managing pending requests
THE brighthub-react-components library SHALL provide a ConnectionPrivacySettings component for privacy controls
THE brighthub-react-components library SHALL provide a TemporaryMuteDialog component for setting timed mutes
THE brighthub-react-components library SHALL provide a ConnectionInsights component for displaying interaction stats
THE brighthub-react-components library SHALL provide a ListTimelineFilter component for filtering timeline by list
All connection components SHALL support theming through BrightHubThemeProvider
All connection components SHALL be accessible and comply with ARIA guidelines
All connection components SHALL use i18n for all user-facing strings via useI18n hook with tComponent(BrightHubComponentId, key) — no hardcoded display text (see Requirement 61)

Requirement 36: Connection Type System Interfaces

User Story: As a developer, I want strongly-typed interfaces for connection features, so that I can ensure type safety.

Acceptance Criteria

THE brighthub-lib library SHALL define IBaseConnectionList generic interface for connection lists
THE brighthub-lib library SHALL define IBaseConnectionCategory generic interface for categories
THE brighthub-lib library SHALL define IBaseConnectionNote generic interface for connection notes
THE brighthub-lib library SHALL define IBaseHub generic interface for hubs
THE brighthub-lib library SHALL define IBaseFollowRequest generic interface for follow requests
THE brighthub-lib library SHALL define IBaseConnectionInsights generic interface for insights data
THE brighthub-lib library SHALL define IBaseConnectionSuggestion generic interface for suggestions
THE brighthub-lib library SHALL define ConnectionStrength enumeration with Strong, Moderate, Weak, and Dormant values
THE brighthub-lib library SHALL define ConnectionVisibility enumeration with Private, FollowersOnly, and Public values
THE brighthub-lib library SHALL define MuteDuration enumeration with predefined duration values
THE brightchain-api-lib library SHALL define API response types for all connection endpoints

Requirement 37: Connection Database Schema

User Story: As a developer, I want database schemas for connection features, so that I can store and query connection data efficiently.

Acceptance Criteria

THE brightchain-db library SHALL define a connection_lists collection schema with name, description, visibility, and owner
THE brightchain-db library SHALL define a connection_list_members collection schema linking lists to users
THE brightchain-db library SHALL define a connection_categories collection schema with name, color, and icon
THE brightchain-db library SHALL define a connection_notes collection schema with note content and connection reference
THE brightchain-db library SHALL define a hubs collection schema with name and owner
THE brightchain-db library SHALL define a hub_members collection schema linking hubs to users
THE brightchain-db library SHALL define a follow_requests collection schema with requester, target, message, and status
THE brightchain-db library SHALL define a connection_metadata collection schema for priority, quiet mode, and category assignments
THE brightchain-db library SHALL define a temporary_mutes collection schema with expiration timestamps
THE brightchain-db library SHALL define a connection_interactions collection schema for tracking interaction history
THE brightchain-db library SHALL define appropriate indexes for list queries, category filters, and suggestion calculations
All connection schemas SHALL support the BrightChain block-based storage model

Requirement 38: Connection Feature E2E Testing

User Story: As a developer, I want E2E tests for connection features, so that I can ensure the connection system works correctly.

Acceptance Criteria

THE brightchain-api-e2e library SHALL include tests for connection list CRUD operations
THE brightchain-api-e2e library SHALL include tests for bulk member add/remove operations
THE brightchain-api-e2e library SHALL include tests for connection category assignment
THE brightchain-api-e2e library SHALL include tests for connection notes CRUD operations
THE brightchain-api-e2e library SHALL include tests for hub creation and membership
THE brightchain-api-e2e library SHALL include tests for hub-restricted post visibility
THE brightchain-api-e2e library SHALL include tests for follow request workflow
THE brightchain-api-e2e library SHALL include tests for priority connection timeline ordering
THE brightchain-api-e2e library SHALL include tests for quiet mode notification suppression
THE brightchain-api-e2e library SHALL include tests for temporary mute expiration
THE brightchain-api-e2e library SHALL include tests for connection suggestions generation
THE brightchain-api-e2e library SHALL include tests for mutual connections calculation
THE brightchain-api-e2e library SHALL include tests for connection import/export
THE brightchain-api-e2e library SHALL include tests for block/mute inheritance on lists
THE brightchain-react-e2e library SHALL include Playwright tests for ConnectionListManager component
THE brightchain-react-e2e library SHALL include Playwright tests for HubManager component
THE brightchain-react-e2e library SHALL include Playwright tests for ConnectionSuggestions component
THE brightchain-react-e2e library SHALL include Playwright tests for FollowRequestList component
THE brightchain-react-e2e library SHALL include Playwright tests for ConnectionPrivacySettings component

Requirement 39: Direct Messaging Core

User Story: As a user, I want to send and receive direct messages with other users, so that I can have private conversations.

Acceptance Criteria

WHEN a user sends a message to another user, THE Messaging_Service SHALL create a conversation if one does not exist and deliver the message
WHEN a user sends a message in an existing conversation, THE Messaging_Service SHALL append the message to the conversation thread
WHEN a user edits their own message within 15 minutes of sending, THE Messaging_Service SHALL update the message content and mark it as edited
WHEN a user deletes their own message, THE Messaging_Service SHALL soft-delete the message and display “Message deleted” placeholder
WHEN a recipient opens a conversation, THE Messaging_Service SHALL mark all unread messages as read and update read receipts
WHEN a user is typing in a conversation, THE Messaging_Service SHALL broadcast a typing indicator to other participants
WHEN a user stops typing for 3 seconds, THE Messaging_Service SHALL remove the typing indicator
WHEN a user adds an emoji reaction to a message, THE Messaging_Service SHALL attach the reaction and notify the message author
WHEN a user removes their reaction from a message, THE Messaging_Service SHALL remove the reaction
THE Messaging_Service SHALL support up to 10 unique emoji reactions per message
WHEN a user searches within a conversation, THE Messaging_Service SHALL return messages matching the query with context
THE Messaging_Service SHALL store messages in the brightchain-db with encryption at rest

Requirement 40: Group Messaging

User Story: As a user, I want to create group conversations with multiple participants, so that I can communicate with several people at once.

Acceptance Criteria

WHEN a user creates a group conversation, THE Messaging_Service SHALL create the group with specified participants and optional name
WHEN a group creator sets a group name, THE Messaging_Service SHALL store and display the name to all participants
WHEN a group creator sets a group avatar, THE Messaging_Service SHALL validate the image and store the reference
WHEN a group admin adds a participant, THE Messaging_Service SHALL add the user and notify existing participants
WHEN a group admin removes a participant, THE Messaging_Service SHALL remove the user and notify remaining participants
WHEN a user leaves a group, THE Messaging_Service SHALL remove the user and notify remaining participants
THE Messaging_Service SHALL support up to 50 participants per group conversation
WHEN a group creator creates the group, THE Messaging_Service SHALL assign them as the initial admin
WHEN a group admin promotes another participant to admin, THE Messaging_Service SHALL update their role
WHEN a group admin demotes another admin, THE Messaging_Service SHALL update their role to participant
THE Messaging_Service SHALL prevent the last admin from leaving without assigning a new admin
WHEN all participants leave a group, THE Messaging_Service SHALL archive the group conversation

Requirement 41: Message Content and Formatting

User Story: As a user, I want to send rich content in my messages, so that I can communicate expressively.

Acceptance Criteria

WHEN a user sends a text message, THE Text_Formatter SHALL process markdown, emojis, and FontAwesome icons
WHEN a user attaches images to a message, THE Messaging_Service SHALL validate formats (JPEG, PNG, GIF, WebP) and store references
THE Messaging_Service SHALL support up to 10 image attachments per message
WHEN a message contains a URL, THE Messaging_Service SHALL generate a link preview with title, description, and thumbnail
WHEN a user replies to a specific message, THE Messaging_Service SHALL create a threaded reply linking to the original message
WHEN a user forwards a message, THE Messaging_Service SHALL create a copy in the target conversation with “Forwarded” indicator
THE Messaging_Service SHALL validate that total attachment size does not exceed 25MB per message
IF an invalid attachment format is provided, THEN THE Messaging_Service SHALL reject the request with a validation error
THE Messaging_Service SHALL support message content up to 2000 characters

Requirement 42: Message Requests and Privacy

User Story: As a user, I want to control who can message me, so that I can protect my privacy and avoid unwanted contact.

Acceptance Criteria

WHEN a non-follower sends a message to a user, THE Messaging_Service SHALL create a message request instead of delivering directly
WHEN a user views their message requests, THE Messaging_Service SHALL return pending requests with sender info and message preview
WHEN a user accepts a message request, THE Messaging_Service SHALL create a conversation and deliver the pending message
WHEN a user declines a message request, THE Messaging_Service SHALL delete the request without notifying the sender
WHEN a user blocks another user, THE Messaging_Service SHALL prevent the blocked user from sending messages or requests
WHEN a user blocks another user with existing conversation, THE Messaging_Service SHALL archive the conversation for both parties
WHEN a user mutes a conversation, THE Messaging_Service SHALL suppress notifications for that conversation
WHEN a user unmutes a conversation, THE Messaging_Service SHALL restore notifications for that conversation
WHEN a user reports a message, THE Messaging_Service SHALL flag the message for review and optionally block the sender
WHEN a user reports a conversation, THE Messaging_Service SHALL flag all messages from the reported user for review
THE Messaging_Service SHALL integrate with the existing block system in brightchain-db
WHEN a mutual follow relationship exists, THE Messaging_Service SHALL deliver messages directly without request

Requirement 43: Conversation Management

User Story: As a user, I want to organize and manage my conversations, so that I can find important messages easily.

Acceptance Criteria

WHEN a user requests their conversation list, THE Messaging_Service SHALL return conversations sorted by most recent activity
THE Messaging_Service SHALL include unread message count for each conversation in the list
WHEN a user pins a conversation, THE Messaging_Service SHALL display it at the top of the conversation list
THE Messaging_Service SHALL support up to 10 pinned conversations per user
WHEN a user unpins a conversation, THE Messaging_Service SHALL restore normal sorting for that conversation
WHEN a user archives a conversation, THE Messaging_Service SHALL hide it from the main inbox
WHEN a user views archived conversations, THE Messaging_Service SHALL return all archived conversations
WHEN a user unarchives a conversation, THE Messaging_Service SHALL restore it to the main inbox
WHEN a user deletes a conversation, THE Messaging_Service SHALL remove it from the user’s view while preserving it for other participants
WHEN a user searches conversations, THE Messaging_Service SHALL return matching conversations by participant name or message content
THE Messaging_Service SHALL support cursor-based pagination for conversation lists

Requirement 44: Messaging React Components

User Story: As a frontend developer, I want React components for messaging, so that I can build the messaging UI efficiently.

Acceptance Criteria

THE brighthub-react-components library SHALL provide a MessagingInbox component for displaying the conversation list
THE brighthub-react-components library SHALL provide a ConversationView component for displaying message threads
THE brighthub-react-components library SHALL provide a MessageComposer component for creating and sending messages
THE brighthub-react-components library SHALL provide a MessageRequestsList component for managing message requests
THE brighthub-react-components library SHALL provide a MessageBubble component for displaying individual messages
THE brighthub-react-components library SHALL provide a TypingIndicator component for showing typing status
THE brighthub-react-components library SHALL provide a ReadReceipt component for showing seen status
THE brighthub-react-components library SHALL provide a MessageReactions component for displaying and adding reactions
THE brighthub-react-components library SHALL provide a GroupConversationSettings component for managing group details
THE brighthub-react-components library SHALL provide a NewConversationDialog component for starting conversations
THE brighthub-react-components library SHALL provide a ConversationSearch component for searching messages
THE brighthub-react-components library SHALL provide a MessagingMenuBadge component for top menu integration with unread count
All messaging components SHALL support theming through BrightHubThemeProvider
All messaging components SHALL be accessible and comply with ARIA guidelines
All messaging components SHALL use i18n for all user-facing strings via useI18n hook with tComponent(BrightHubComponentId, key) — no hardcoded display text (see Requirement 61)

Requirement 45: Messaging API Endpoints

User Story: As a developer, I want RESTful API endpoints for messaging, so that I can integrate messaging with frontend applications.

Acceptance Criteria

THE BrightHub_System SHALL expose GET /api/brighthub/messages/conversations for retrieving conversation list
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations for creating new conversations
THE BrightHub_System SHALL expose GET /api/brighthub/messages/conversations/:id for retrieving a single conversation with messages
THE BrightHub_System SHALL expose DELETE /api/brighthub/messages/conversations/:id for deleting a conversation
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations/:id/messages for sending a message
THE BrightHub_System SHALL expose PUT /api/brighthub/messages/:messageId for editing a message
THE BrightHub_System SHALL expose DELETE /api/brighthub/messages/:messageId for deleting a message
THE BrightHub_System SHALL expose POST /api/brighthub/messages/:messageId/reactions for adding a reaction
THE BrightHub_System SHALL expose DELETE /api/brighthub/messages/:messageId/reactions/:emoji for removing a reaction
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations/:id/read for marking messages as read
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations/:id/typing for sending typing indicator
THE BrightHub_System SHALL expose GET /api/brighthub/messages/requests for retrieving message requests
THE BrightHub_System SHALL expose POST /api/brighthub/messages/requests/:id/accept for accepting a request
THE BrightHub_System SHALL expose POST /api/brighthub/messages/requests/:id/decline for declining a request
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations/:id/pin for pinning a conversation
THE BrightHub_System SHALL expose DELETE /api/brighthub/messages/conversations/:id/pin for unpinning a conversation
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations/:id/archive for archiving a conversation
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations/:id/unarchive for unarchiving a conversation
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations/:id/mute for muting notifications
THE BrightHub_System SHALL expose DELETE /api/brighthub/messages/conversations/:id/mute for unmuting notifications
THE BrightHub_System SHALL expose POST /api/brighthub/messages/:messageId/report for reporting a message
THE BrightHub_System SHALL expose GET /api/brighthub/messages/conversations/:id/search for searching within a conversation
THE BrightHub_System SHALL expose GET /api/brighthub/messages/search for searching across all conversations
THE BrightHub_System SHALL expose POST /api/brighthub/messages/conversations/:id/participants for adding group participants
THE BrightHub_System SHALL expose DELETE /api/brighthub/messages/conversations/:id/participants/:userId for removing group participants
THE BrightHub_System SHALL expose PUT /api/brighthub/messages/conversations/:id/settings for updating group settings
THE BrightHub_System SHALL expose POST /api/brighthub/messages/:messageId/forward for forwarding a message
THE BrightHub_System SHALL return appropriate HTTP status codes for success and error responses

Requirement 46: Messaging Type System Interfaces

User Story: As a developer, I want strongly-typed interfaces for messaging features, so that I can ensure type safety.

Acceptance Criteria

THE brighthub-lib library SHALL define IBaseConversation generic interface for conversations
THE brighthub-lib library SHALL define IBaseDirectMessage generic interface for messages
THE brighthub-lib library SHALL define IBaseMessageRequest generic interface for message requests
THE brighthub-lib library SHALL define IBaseMessageReaction generic interface for reactions
THE brighthub-lib library SHALL define IBaseReadReceipt generic interface for read receipts
THE brighthub-lib library SHALL define IBaseGroupConversation generic interface extending IBaseConversation
THE brighthub-lib library SHALL define IBaseMessageThread generic interface for threaded replies
THE brighthub-lib library SHALL define ConversationType enumeration with Direct and Group values
THE brighthub-lib library SHALL define MessageRequestStatus enumeration with Pending, Accepted, and Declined values
THE brighthub-lib library SHALL define GroupParticipantRole enumeration with Admin and Participant values
THE brighthub-lib library SHALL define ConversationStatus enumeration with Active, Archived, and Muted values
THE brightchain-api-lib library SHALL define API response types for all messaging endpoints

Requirement 47: Messaging Database Schema

User Story: As a developer, I want database schemas for messaging features, so that I can store and query messaging data efficiently.

Acceptance Criteria

THE brightchain-db library SHALL define a conversations collection schema with type, participants, name, avatar, and timestamps
THE brightchain-db library SHALL define a messages collection schema with conversation reference, sender, content, attachments, and timestamps
THE brightchain-db library SHALL define a message_requests collection schema with sender, recipient, message preview, and status
THE brightchain-db library SHALL define a message_reactions collection schema with message reference, user, and emoji
THE brightchain-db library SHALL define a read_receipts collection schema with conversation, user, and last read timestamp
THE brightchain-db library SHALL define a conversation_participants collection schema with conversation, user, role, and settings
THE brightchain-db library SHALL define a pinned_conversations collection schema with user and conversation reference
THE brightchain-db library SHALL define a archived_conversations collection schema with user and conversation reference
THE brightchain-db library SHALL define a muted_conversations collection schema with user, conversation, and optional expiration
THE brightchain-db library SHALL define a message_reports collection schema with reporter, message, reason, and status
THE brightchain-db library SHALL define indexes on conversations for participant lookups and recent activity sorting
THE brightchain-db library SHALL define indexes on messages for conversation queries and full-text search
THE brightchain-db library SHALL define indexes on message_requests for recipient lookups
All messaging schemas SHALL support the BrightChain block-based storage model

Requirement 48: Messaging E2E Testing

User Story: As a developer, I want E2E tests for messaging features, so that I can ensure the messaging system works correctly.

Acceptance Criteria

THE brightchain-api-e2e library SHALL include tests for conversation creation (direct and group)
THE brightchain-api-e2e library SHALL include tests for sending, editing, and deleting messages
THE brightchain-api-e2e library SHALL include tests for message reactions add and remove
THE brightchain-api-e2e library SHALL include tests for read receipt updates
THE brightchain-api-e2e library SHALL include tests for message request workflow (create, accept, decline)
THE brightchain-api-e2e library SHALL include tests for group participant management (add, remove, role changes)
THE brightchain-api-e2e library SHALL include tests for conversation pinning and unpinning
THE brightchain-api-e2e library SHALL include tests for conversation archiving and unarchiving
THE brightchain-api-e2e library SHALL include tests for conversation muting and unmuting
THE brightchain-api-e2e library SHALL include tests for message search within conversations
THE brightchain-api-e2e library SHALL include tests for cross-conversation search
THE brightchain-api-e2e library SHALL include tests for message forwarding
THE brightchain-api-e2e library SHALL include tests for threaded replies
THE brightchain-api-e2e library SHALL include tests for block integration preventing messages
THE brightchain-api-e2e library SHALL include tests for message reporting
THE brightchain-react-e2e library SHALL include Playwright tests for MessagingInbox component
THE brightchain-react-e2e library SHALL include Playwright tests for ConversationView component
THE brightchain-react-e2e library SHALL include Playwright tests for MessageComposer component
THE brightchain-react-e2e library SHALL include Playwright tests for MessageRequestsList component
THE brightchain-react-e2e library SHALL include Playwright tests for GroupConversationSettings component
THE brightchain-react-e2e library SHALL include Playwright tests for NewConversationDialog component

Requirement 49: Real-Time Messaging

User Story: As a user, I want real-time message delivery and notifications, so that I can have fluid conversations.

Acceptance Criteria

WHEN a message is sent, THE Messaging_Service SHALL deliver it to online recipients in real-time via WebSocket
WHEN a user comes online, THE Messaging_Service SHALL deliver any pending messages immediately
WHEN a typing indicator is sent, THE Messaging_Service SHALL broadcast it to conversation participants within 100ms
WHEN a message is read, THE Messaging_Service SHALL broadcast read receipt updates to the sender in real-time
WHEN a reaction is added or removed, THE Messaging_Service SHALL broadcast the update to conversation participants
WHEN a participant is added or removed from a group, THE Messaging_Service SHALL notify all participants in real-time
THE Messaging_Service SHALL maintain WebSocket connections with automatic reconnection on disconnect
WHEN a user receives a new message while offline, THE BrightHub_System SHALL create a notification upon next login

Requirement 50: Messaging Notifications Integration

User Story: As a user, I want to receive notifications for messaging activity, so that I stay informed about new messages.

Acceptance Criteria

WHEN a user receives a new direct message, THE BrightHub_System SHALL create a notification for the recipient
WHEN a user receives a message in a group conversation, THE BrightHub_System SHALL create a notification for all participants except the sender
WHEN a user receives a message request, THE BrightHub_System SHALL create a notification for the recipient
WHEN a message request is accepted, THE BrightHub_System SHALL create a notification for the original sender
WHEN a user is added to a group conversation, THE BrightHub_System SHALL create a notification for the added user
WHILE a conversation is muted, THE BrightHub_System SHALL suppress notifications for that conversation
WHEN a user’s message receives a reaction, THE BrightHub_System SHALL create a notification for the message author
THE BrightHub_System SHALL aggregate multiple message notifications from the same conversation within 5 minutes
THE BrightHub_System SHALL display unread message count badge in the top navigation menu
WHEN a user clears notifications, THE BrightHub_System SHALL mark messaging notifications as read but preserve unread message counts

Requirement 51: Notification Center UI

User Story: As a user, I want a notification center in the top menu, so that I can quickly see and manage my notifications without leaving my current page.

Acceptance Criteria

THE Notification_Bell component SHALL display a bell icon in the TopMenu with an unread notification count badge
WHEN the unread count exceeds 99, THE Notification_Bell component SHALL display “99+”
WHEN the user clicks the Notification_Bell, THE Notification_Dropdown SHALL appear showing the 10 most recent notifications
THE Notification_Dropdown SHALL display each notification with actor avatar, action description, timestamp, and read/unread indicator
THE Notification_Dropdown SHALL include a “View all notifications” link navigating to the full notifications page
THE Notification_Dropdown SHALL include a “Mark all as read” action button
WHEN a new notification arrives, THE Notification_Bell SHALL update the badge count without page refresh
WHEN a new notification arrives while the dropdown is open, THE Notification_Dropdown SHALL prepend the new notification to the list
THE Notification_Dropdown SHALL close when the user clicks outside of it
THE Notification_Dropdown SHALL support keyboard navigation for accessibility

Requirement 52: Modular Notification System Architecture

User Story: As a developer, I want a modular notification system, so that any component in the application can access and respond to notification state.

Acceptance Criteria

THE Notification_Provider context SHALL wrap the application and manage global notification state
THE Notification_Provider SHALL expose a useNotifications hook for accessing notification state and actions
THE useNotifications hook SHALL provide: notifications array, unreadCount, markAsRead, markAllAsRead, deleteNotification, and refreshNotifications functions
THE Notification_Provider SHALL establish a WebSocket subscription for real-time notification updates
WHEN the WebSocket connection is lost, THE Notification_Provider SHALL automatically reconnect with exponential backoff
THE Notification_Provider SHALL cache notifications locally and sync with server on reconnection
THE Notification_Provider SHALL support filtering notifications by Notification_Category
THE Notification_Provider SHALL emit events when notifications are received, allowing components to react independently
THE useNotifications hook SHALL provide a subscribe function for components to listen to specific notification types
THE Notification_Provider SHALL deduplicate notifications to prevent duplicate display

Requirement 53: Notification Display Components

User Story: As a frontend developer, I want reusable notification display components, so that I can build consistent notification UIs across the application.

Acceptance Criteria

THE brighthub-react-components library SHALL provide a NotificationBell component for TopMenu integration
THE brighthub-react-components library SHALL provide a NotificationDropdown component for the quick-view panel
THE brighthub-react-components library SHALL provide a NotificationItem component for rendering individual notifications
THE brighthub-react-components library SHALL provide a NotificationList component for the full notifications page
THE brighthub-react-components library SHALL provide a NotificationPreferences component for managing notification settings
THE brighthub-react-components library SHALL provide a NotificationCategoryFilter component for filtering by category
THE NotificationItem component SHALL support click-through navigation to the relevant content
THE NotificationItem component SHALL display grouped notifications with expandable details (e.g., “5 people liked your post”)
THE NotificationList component SHALL support infinite scroll pagination
THE NotificationList component SHALL support filtering by read/unread status
All notification components SHALL support theming through BrightHubThemeProvider
All notification components SHALL be accessible and comply with ARIA guidelines
All notification components SHALL use i18n for all user-facing strings via useI18n hook with tComponent(BrightHubComponentId, key) — no hardcoded display text (see Requirement 61)

Requirement 54: Notification Actions

User Story: As a user, I want to manage my notifications, so that I can keep my notification list organized and relevant.

Acceptance Criteria

WHEN a user clicks a notification, THE Notification_Service SHALL mark it as read and navigate to the relevant content
WHEN a user clicks “Mark as read” on a notification, THE Notification_Service SHALL mark only that notification as read
WHEN a user clicks “Mark all as read”, THE Notification_Service SHALL mark all notifications as read
WHEN a user deletes a notification, THE Notification_Service SHALL remove it from their notification list
WHEN a user clicks “Clear all”, THE Notification_Service SHALL delete all notifications for that user
THE Notification_Service SHALL support bulk delete operations for selected notifications
WHEN a user hovers over a notification, THE NotificationItem SHALL display action buttons (mark read, delete)
THE Notification_Service SHALL support undo for delete operations within 5 seconds

Requirement 55: Notification Categories and Grouping

User Story: As a user, I want notifications organized by category and grouped by type, so that I can quickly understand my notification activity.

Acceptance Criteria

THE Notification_Service SHALL categorize notifications into: social, messages, connections, and system
THE social category SHALL include: likes, reposts, quotes, replies, and mentions
THE messages category SHALL include: new messages, message requests, and message reactions
THE connections category SHALL include: new followers, follow requests, and reconnect reminders
THE system category SHALL include: account alerts, security notifications, and feature announcements
WHEN multiple users perform the same action on the same content within 1 hour, THE Notification_Service SHALL group them into a single notification
THE grouped notification SHALL display the count and list of actors (e.g., “Alice, Bob, and 3 others liked your post”)
WHEN a user expands a grouped notification, THE NotificationItem SHALL display individual actors with timestamps
THE Notification_Service SHALL support ungrouping notifications in user preferences
THE NotificationCategoryFilter component SHALL allow filtering the notification list by one or more categories

Requirement 56: Notification Preferences

User Story: As a user, I want to control my notification preferences, so that I only receive notifications I care about.

Acceptance Criteria

THE NotificationPreferences component SHALL allow enabling/disabling notifications per Notification_Category
THE NotificationPreferences component SHALL allow configuring email notification preferences per category
THE NotificationPreferences component SHALL allow configuring push notification preferences per category (for future mobile support)
THE Notification_Service SHALL respect user preferences when creating notifications
WHEN a user enables Quiet_Hours, THE Notification_Service SHALL suppress in-app notifications during the specified time window
THE NotificationPreferences component SHALL allow setting Quiet_Hours start and end times with timezone support
WHEN a user enables Do_Not_Disturb mode, THE Notification_Service SHALL suppress all non-critical notifications
THE NotificationPreferences component SHALL allow setting Do_Not_Disturb duration (1 hour, 8 hours, 24 hours, until manually disabled)
THE Notification_Service SHALL still deliver critical system notifications (security alerts) even during Do_Not_Disturb
THE NotificationPreferences component SHALL allow configuring notification sound preferences (on/off, custom sounds)
THE Notification_Service SHALL store preferences in the user profile and sync across devices
WHEN preferences are updated, THE Notification_Provider SHALL immediately reflect the changes without page refresh

Requirement 57: Notification API Endpoints

User Story: As a developer, I want RESTful API endpoints for notification management, so that I can integrate the notification system with frontend applications.

Acceptance Criteria

THE BrightHub_System SHALL expose GET /api/brighthub/notifications for retrieving paginated notifications
THE BrightHub_System SHALL expose GET /api/brighthub/notifications/unread-count for retrieving unread notification count
THE BrightHub_System SHALL expose POST /api/brighthub/notifications/:id/read for marking a notification as read
THE BrightHub_System SHALL expose POST /api/brighthub/notifications/read-all for marking all notifications as read
THE BrightHub_System SHALL expose DELETE /api/brighthub/notifications/:id for deleting a notification
THE BrightHub_System SHALL expose DELETE /api/brighthub/notifications for bulk deleting notifications
THE BrightHub_System SHALL expose GET /api/brighthub/notifications/preferences for retrieving notification preferences
THE BrightHub_System SHALL expose PUT /api/brighthub/notifications/preferences for updating notification preferences
THE BrightHub_System SHALL expose POST /api/brighthub/notifications/preferences/quiet-hours for setting quiet hours
THE BrightHub_System SHALL expose POST /api/brighthub/notifications/preferences/dnd for enabling/disabling Do Not Disturb
THE BrightHub_System SHALL expose WebSocket endpoint /ws/notifications for real-time notification delivery
THE BrightHub_System SHALL return appropriate HTTP status codes for success and error responses

Requirement 58: Notification Type System Interfaces

User Story: As a developer, I want strongly-typed interfaces for notification features, so that I can ensure type safety across the notification system.

Acceptance Criteria

THE brighthub-lib library SHALL define IBaseNotification generic interface with id, type, category, actorId, targetId, content, read, createdAt, and clickThroughUrl fields
THE brighthub-lib library SHALL define IBaseNotificationGroup generic interface for grouped notifications with actors array and count
THE brighthub-lib library SHALL define IBaseNotificationPreferences generic interface for user notification settings
THE brighthub-lib library SHALL define NotificationCategory enumeration with Social, Messages, Connections, and System values
THE brighthub-lib library SHALL define NotificationType enumeration with Like, Reply, Mention, Follow, FollowRequest, Repost, Quote, NewMessage, MessageRequest, MessageReaction, SystemAlert values
THE brighthub-lib library SHALL define NotificationChannel enumeration with InApp, Email, and Push values
THE brighthub-lib library SHALL define INotificationProviderState interface for the context state
THE brighthub-lib library SHALL define INotificationActions interface for the context actions
THE brightchain-api-lib library SHALL define API response types for all notification endpoints
THE brighthub-lib library SHALL define IQuietHoursConfig interface with startTime, endTime, and timezone fields
THE brighthub-lib library SHALL define IDoNotDisturbConfig interface with enabled, duration, and expiresAt fields

Requirement 59: Notification Database Schema Extensions

User Story: As a developer, I want database schema extensions for notification UI features, so that I can store notification preferences and grouping data.

Acceptance Criteria

THE brightchain-db library SHALL extend the notifications collection schema with category, clickThroughUrl, and groupId fields
THE brightchain-db library SHALL define a notification_preferences collection schema with userId, categorySettings, channelSettings, quietHours, and dndConfig
THE brightchain-db library SHALL define a notification_groups collection schema with groupKey, notificationIds, actorIds, and count
THE brightchain-db library SHALL define indexes on notifications for category filtering and unread queries
THE brightchain-db library SHALL define indexes on notification_preferences for user lookups
All notification schemas SHALL support the BrightChain block-based storage model

Requirement 60: Notification UI E2E Testing

User Story: As a developer, I want E2E tests for notification UI features, so that I can ensure the notification system works correctly.

Acceptance Criteria

THE brightchain-api-e2e library SHALL include tests for notification CRUD operations
THE brightchain-api-e2e library SHALL include tests for notification preference updates
THE brightchain-api-e2e library SHALL include tests for notification grouping logic
THE brightchain-api-e2e library SHALL include tests for quiet hours enforcement
THE brightchain-api-e2e library SHALL include tests for Do Not Disturb mode
THE brightchain-api-e2e library SHALL include tests for real-time notification delivery via WebSocket
THE brightchain-react-e2e library SHALL include Playwright tests for NotificationBell component badge updates
THE brightchain-react-e2e library SHALL include Playwright tests for NotificationDropdown open/close behavior
THE brightchain-react-e2e library SHALL include Playwright tests for NotificationList infinite scroll
THE brightchain-react-e2e library SHALL include Playwright tests for NotificationPreferences form interactions
THE brightchain-react-e2e library SHALL include Playwright tests for notification click-through navigation
THE brightchain-react-e2e library SHALL include Playwright tests for mark as read and delete actions
THE brightchain-react-e2e library SHALL include Playwright tests for notification category filtering
THE brightchain-react-e2e library SHALL include Playwright tests for grouped notification expansion

Requirement 61: Internationalization (i18n) Support

User Story: As a developer, I want all user-facing strings to be internationalized from the start, so that we avoid costly retrofitting and can support multiple languages.

Acceptance Criteria

THE brighthub-lib library SHALL define a BrightHubComponentId and BrightHubStrings enum following the existing @digitaldefiance/i18n-lib createI18nStringKeys pattern used by BrightChainStrings (already in place)
THE brighthub-lib library SHALL define i18n string keys for all user-facing text including error messages, validation messages, UI labels, and notification content templates
THE brighthub-lib library SHALL provide a translate helper function scoped to the BrightHub component, following the same pattern as brightchain-lib’s translate() (already in place)
All React components in brighthub-react-components SHALL use the useI18n hook from @digitaldefiance/express-suite-react-components with tComponent(BrightHubComponentId, key) for all user-facing strings — no hardcoded display text
All API error messages and validation messages in brightchain-api-lib BrightHub services SHALL use BrightHubStrings keys via the translate function instead of hardcoded strings
All notification content strings SHALL use i18n template keys with variable substitution (e.g., {ACTOR_NAME} liked your post)
THE brighthub-lib library SHALL provide default English (en-US) translations for all string keys
All BrightHub i18n string keys SHALL follow the naming convention BrightHub_{Component}_{Description} (e.g., BrightHub_PostComposer_CharacterLimitExceeded)
THE brighthub-react-components test suite SHALL mock useI18n consistently, following the pattern established in brightmail-react-components tests
THE brighthub-lib library SHALL register its component config with the global i18n engine during initialization, following the createBrightChainComponentConfig() pattern (already in place)

Requirements Document

Introduction

Glossary

Requirements

Requirement 1: Post Creation and Management

Acceptance Criteria

Requirement 2: Thread and Reply Management

Acceptance Criteria

Requirement 3: Social Interactions (Likes, Reposts, Quotes)

Acceptance Criteria

Requirement 4: User Following System

Acceptance Criteria

Requirement 5: Timeline and Feed Generation

Acceptance Criteria

Requirement 6: Rich Text Formatting

Acceptance Criteria

Requirement 7: Mentions and Hashtags

Acceptance Criteria

Requirement 8: User Profile Management

Acceptance Criteria

Requirement 9: Notification System Core

Acceptance Criteria

Requirement 10: Search Functionality

Acceptance Criteria

Requirement 11: API Endpoints

Acceptance Criteria

Requirement 12: React Component Library

Acceptance Criteria

Requirement 13: Type System and Interfaces

Acceptance Criteria

Requirement 14: Database Schema

Acceptance Criteria

Requirement 15: End-to-End Testing

Acceptance Criteria

Requirement 16: Integration with Existing Text Formatting Library

Acceptance Criteria

Requirement 17: Media Attachments

Acceptance Criteria

Requirement 18: Block and Mute Functionality

Acceptance Criteria

Requirement 19: Connection Lists Management

Acceptance Criteria

Requirement 20: Connection Categories

Acceptance Criteria

Requirement 21: Connection Notes

Acceptance Criteria

Requirement 22: Connection Import and Export

Acceptance Criteria

Requirement 23: Priority Connections

Acceptance Criteria

Requirement 24: Quiet Mode for Connections

Acceptance Criteria

Requirement 25: Temporary Mute with Auto-Unmute

Acceptance Criteria

Requirement 26: Connection Discovery and Suggestions

Acceptance Criteria

Requirement 27: Connection Strength Indicators

Acceptance Criteria

Requirement 28: Mutual Connections Display

Acceptance Criteria

Requirement 29: Connection History and Insights

Acceptance Criteria

Requirement 30: Hubs and Close Friends Content

Acceptance Criteria

Requirement 31: Granular Privacy Controls

Acceptance Criteria

Requirement 32: Block and Mute Inheritance for Lists

Acceptance Criteria

Requirement 33: Connection List Following

Acceptance Criteria

Requirement 34: Connection Management API Endpoints

Acceptance Criteria

Requirement 35: Connection Management React Components

Acceptance Criteria

Requirement 36: Connection Type System Interfaces

Acceptance Criteria

Requirement 37: Connection Database Schema

Acceptance Criteria

Requirement 38: Connection Feature E2E Testing

Acceptance Criteria