Community Subgraph — Integration Guide

Overview

The community service powers trust and engagement features. It uses polymorphic relationships to attach social primitives (Reviews, Q&A, Issues, Discussions) to any federated entity (Products, Malets, Services). Assignment workflows enable Malet staff to triage and own Issues and Discussions, with real-time notification dispatch to the Alerts service.

Architecture at a Glance

Core Systems

1. Reviews

Supports star ratings (1-5), text content, nested owners responses, and aggregate distribution.

• Polymorphic: Associates via subjectId and subjectType (e.g. "Product").
• Quality Signals: Users can upvote reviews via a "Helpful Votes" mechanism (with server-side deduplication).

2. Moderation Workflow

A safety-first approach to user-generated content.

• States: PENDING, APPROVED, REJECTED.
• Supports unified queueing for Admin/Malet Owner approval dashboards.

3. SLA Tracking & Issues

Visitor support and fulfillment tracking.

• Entities have SLA resolution deadlines.
• System monitors breach performance to supply Malet Owner scorecards.

4. Assignment Orchestration

Malet staff can assign Issues and Discussions to team members for triage and resolution.

• 5 GraphQL mutations: assignIssue, unassignIssue, changeIssueState, assignDiscussion, unassignDiscussion
• 7 TCP event types dispatched to the Alerts service for notification fan-out
• Preference-aware multi-channel delivery (email + push) with quiet hours support

See the full guide: Community Orchestration (Community category)

GraphQL API Examples

Rate a Product

mutation AddReview($input: ReviewInput!) {
	createReview(input: $input) {
		id
		rating
		text
	}
}

Upvote a Review

mutation VoteHelpful($reviewId: ID!) {
	markReviewHelpful(reviewId: $reviewId) {
		id
		helpfulCount
	}
}

Assign an Issue

mutation AssignIssue($input: AssignIssueInput!) {
	assignIssue(input: $input) {
		id
		issueID
		assignedTo
		assignedAt
	}
}

Setup

COMMUNITY_SERVICE_PORT=3007
MONGODB_URI=mongodb://localhost:27017/ngwenya
ALERTS_SERVICE_HOST=localhost
ALERTS_SERVICE_PORT_TCP=3012