Community Orchestration

Assignment workflows for Issues and Discussions with real-time notification dispatch to Malet staff via the Alerts service.

Architecture Overview

Community Orchestration bridges two services: the community subgraph owns the assignment state machine and GraphQL API, while the alerts subgraph handles notification fan-out with preference-aware, multi-channel delivery.

Event Flow

┌─────────────────────┐    TCP emit     ┌─────────────────────┐
│  Community Service  │ ──────────────► │   Alerts Service    │
│                     │                 │                     │
│  AssignmentService  │  issue_assigned │ CommunityAlerts-    │
│  AssignmentResolver │  issue_created  │ Controller          │
│  AlertsClient       │  state_changed  │                     │
│                     │  disc_assigned  │  → NodesClient      │
│                     │  disc_created   │  → AlertDelivery    │
└─────────────────────┘                 └─────────────────────┘
                                               │
                                     ┌─────────┼─────────┐
                                     ▼         ▼         ▼
                                   Email     Push    (In-App)

GraphQL Mutations

Issue Assignment

Assign a Malet staff member to triage an Issue. Only Malet Owners and authorized members should execute assignment mutations.

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

Variables:

{
	"input": {
		"issueId": "680abcdef1234567890abcde",
		"assigneeId": "user-staff-member"
	}
}

Unassign Issue

Remove the current assignee from an Issue, returning it to the unassigned queue.

mutation UnassignIssue($issueId: ID!) {
	unassignIssue(issueId: $issueId) {
		id
		assignedTo
	}
}

Change Issue State

Transition an Issue through the state machine: OPEN → IN_PROGRESS → RESOLVED → CLOSED.

mutation ChangeIssueState($issueId: ID!, $state: IssueState!) {
	changeIssueState(issueId: $issueId, state: $state) {
		id
		issueID
		state
	}
}

Valid states: OPEN, IN_PROGRESS, RESOLVED, CLOSED

When an Issue transitions to CLOSED, the system automatically records a resolvedAt timestamp for SLA compliance tracking.

Discussion Assignment

Discussions follow the same assignment pattern as Issues, allowing Malet staff to take ownership.

mutation AssignDiscussion($input: AssignDiscussionInput!) {
	assignDiscussion(input: $input) {
		id
		discussionID
		name
		assignedTo
		assignedAt
	}
}

mutation UnassignDiscussion($discussionId: ID!) {
	unassignDiscussion(discussionId: $discussionId) {
		id
		assignedTo
	}
}

Event Types

Every assignment and state-change mutation emits a TCP event to the Alerts service. These are fire-and-forget — the community service does not wait for delivery confirmation.

Event Payload Example

// issue_assigned event payload
interface IssueAssignedEvent {
	issueId: string; // MongoDB document ID
	issueID: string; // Human-readable ID (e.g. "I-a8f3b2")
	title: string; // Issue title
	subjectId: string; // Malet, Product, or Service ID
	subjectType: string; // "MALET" | "PRODUCT" | "SERVICE" | "ORDER"
	assignedTo: string; // User ID of the assignee
	assignedBy: string; // User ID of the actor who assigned
}

Notification Delivery

The CommunityAlertsController in the Alerts service consumes events and applies preference-aware routing before dispatching.

Delivery Logic

1. Profile Resolution — Fetch assignee profile via NodesClientService to obtain email, push tokens, and notification preferences.
2. Quiet Hours Check — If the user has configured quiet hours (e.g. 22:00–08:00), notifications are suppressed during that window.
3. Channel Dispatch — Based on the user's saved preferences:
   • Email: Always sent for assigned and state_changed events (unless quiet hours apply).
   • Push: Sent for assigned events and URGENT priority issue_created events.
4. Priority Escalation — Issues with URGENT priority override normal rules and trigger immediate push notifications on creation, ensuring critical customer issues surface instantly.

Preference Integration

Notification preferences are managed via the existing Account Settings → Notifications panel. The community events respect the same email/sms/push toggles used by Murchase and Workroom notifications.

// Preferences checked per delivery
type Channel = 'email' | 'sms' | 'push';
type Category = 'murchases' | 'workroom' | 'promotions' | 'security' | 'community';

Entity Schema

Issue Fields (Added)

Discussion Fields (Added)

Environment Configuration

The community service requires TCP connectivity to the alerts service for event dispatch.

# Community service (.env)
COMMUNITY_SERVICE_PORT=3007
ALERTS_SERVICE_HOST=localhost      # Alerts TCP hostname
ALERTS_SERVICE_PORT_TCP=3012      # Alerts TCP port

No configuration changes are needed on the alerts service — it already listens on the configured TCP port.

Module Structure

apps/community/src/
├── assignment/
│   ├── assignment.module.ts         # Module wiring
│   ├── assignment.service.ts        # Core assignment logic
│   ├── assignment.resolver.ts       # GraphQL mutations
│   ├── assignment.service.spec.ts   # 14 unit tests
│   ├── assignment.resolver.spec.ts  # 6 unit tests
│   └── dto/
│       ├── assign-issue.input.ts
│       └── assign-discussion.input.ts
└── external/
    ├── alerts.client.ts             # TCP event emitter
    ├── events.ts                    # 7 event payload interfaces
    └── external.module.ts           # ClientsModule registration

apps/alerts/src/
└── community-alerts/
    ├── community-alerts.controller.ts       # @EventPattern handlers
    ├── community-alerts.controller.spec.ts  # 8 unit tests
    ├── community-alerts.module.ts
    └── dto/
        └── index.ts                         # Payload DTOs

Testing

Running Tests

# Unit tests (community + alerts)
make test-pattern PATTERN=community
make test-pattern PATTERN=alerts

# E2E tests
make test-e2e-pattern PATTERN=community

Note: E2E tests override AlertsClient with a mock since the Alerts service isn't running during test execution. This follows the same pattern used by the Murchases E2E suite.

Related

• Community Features — Base community system — reviews, Q&A, ratings, and moderation that Orchestration extends
• Alerts Resilience & Delivery Tracking — DLQ retry and multi-channel delivery for the notifications dispatched by Orchestration
• Alerts & Notifications — Frontend toast system and notification monitoring
• Organizations & Permissions — Permission infrastructure used to gate assignment mutations