Skip to main content

Communication Recipient Targeting System

📋 Table of Contents​

  1. Overview
  2. Quick Start
  3. Documentation Index
  4. Problem & Solution
  5. Key Features
  6. Architecture Summary
  7. Getting Started

Overview​

The Recipient Targeting System is an enhancement to the communication module that allows businesses to control WHO receives each type of communication (low stock alerts, reports, invoices, etc.) through flexible, configurable rules.

What This Solves​

Before: All communications go to ALL business users (hardcoded in handlers)

After: Businesses configure recipients via admin UI:

  • Send to specific roles (e.g., all inventory managers)
  • Send to custom groups (e.g., "Finance Team" with mixed users + external emails)
  • Send to ad-hoc contacts (e.g., specific emails/phone numbers)
  • Combine all the above

Quick Start​

For Product Managers / Business Users​

👉 Start here: RECIPIENT-TARGETING-PROPOSAL.md

  • Executive summary
  • Real-world examples
  • UI mockups
  • Business benefits

For Developers​

👉 Start here: recipient-targeting-implementation-checklist.md

  • Step-by-step implementation guide
  • Code examples
  • Testing strategies

For Database Admins​

👉 Start here: Migration file 2025-10-26t00:00:00.000z-communication-recipient-targeting.mjs

  • Database schema
  • Indexes
  • Migration up/down scripts

For Architects​

👉 Start here: recipient-targeting-system-design.md

  • Detailed architecture
  • Data flow diagrams
  • Service design

Documentation Index​

1. Proposal Summary 📄​

File: RECIPIENT-TARGETING-PROPOSAL.md

Audience: Everyone (overview document)

Contents:

  • Executive summary
  • Current vs proposed state
  • Real-world examples
  • Mockups
  • Timeline
  • Risk assessment

When to read: First document to review, especially for decision-makers

2. Changes Summary 📊​

File: recipient-targeting-changes-summary.md

Audience: Technical leads, developers

Contents:

  • What changes in the system
  • Before/after comparisons
  • Configuration examples
  • API examples
  • Decision matrix

When to read: After reading the proposal, before implementation

3. Architecture Design 🏗️​

File: recipient-targeting-system-design.md

Audience: Architects, senior developers

Contents:

  • Detailed architecture
  • Core tables explained
  • Data flow diagrams
  • Service design patterns
  • Usage examples
  • Future enhancements

When to read: During design review or before coding

4. Entity Relationship Diagram 📐​

File: recipient-targeting-erd.md

Audience: Database admins, backend developers

Contents:

  • Visual ERD diagrams
  • Table relationships explained
  • Polymorphic relationships
  • Index strategies
  • Data flow example with SQL queries

When to read: Before implementing repositories or understanding data model

5. Implementation Checklist ✅​

File: recipient-targeting-implementation-checklist.md

Audience: Development team

Contents:

  • 10-phase implementation plan
  • Detailed tasks for each phase
  • Code templates
  • Testing strategies
  • Timeline estimates

When to read: During sprint planning and implementation

6. Database Migration 💾​

File: packages/backend/database/src/migrations/2025-10-26t00:00:00.000z-communication-recipient-targeting.mjs

Audience: Database admins, backend developers

Contents:

  • SQL DDL for 4 new tables
  • Indexes
  • Constraints
  • Rollback script

When to read: Before running migration

Problem & Solution​

The Problem​

Current communication handlers are hardcoded:

// ❌ Problem: Hardcoded recipient logic
const businessUsers = await this.businessUsersService.findByBusinessId(businessId);

for (const user of businessUsers) {
  await this.communicationsService.send({ 
    recipientContact: user.email 
  });
}

Issues:

  • ❌ Can't filter by role
  • ❌ Can't send to external contacts (suppliers, accountants)
  • ❌ Can't create distribution lists
  • ❌ Changing recipients requires code changes + deployment
  • ❌ Every business gets same recipients
  • ❌ No audit trail

The Solution​

Flexible, rule-based recipient resolution:

// ✅ Solution: Dynamic, rule-based resolution
const recipients = await this.recipientResolverService.resolveRecipients(
  businessId,
  'low_stock_alert',
  'email'
);
// Recipients resolved from database rules:
// - All users with role 'inventory_manager'
// - All members of "Purchasing Team" group (users + external emails)
// - Ad-hoc: supplier@vendor.com

for (const recipient of recipients) {
  await this.communicationsService.send({
    recipientContact: recipient.contact,
    metadata: { source: recipient.source } // Audit trail
  });
}

Benefits:

  • ✅ Filter by roles, groups, or ad-hoc
  • ✅ Include external contacts
  • ✅ Businesses configure via admin UI
  • ✅ No code changes to modify recipients
  • ✅ Per-business customization
  • ✅ Full audit trail

Key Features​

1. Role-Based Targeting​

Send to all users with a specific role.

Example:

"Send low stock alerts to all inventory managers"
→ Resolves to all business users with role 'inventory_manager'

2. Custom Groups​

Create groups with mixed internal users and external contacts.

Example:

"Finance Team" group:
- John Doe (internal user)
- Jane Smith (internal user)
- cpa@accounting-firm.com (external email)
- +1-555-ACCOUNTANT (external phone)

3. Ad-Hoc Recipients​

Include specific emails or phone numbers.

Example:

"Send emergency alerts to security service: +1-555-SECURITY"

4. Multi-Channel Support​

Different recipients per channel.

Example:

Low Stock Alerts:
- Email → inventory_manager role + Purchasing Team group
- SMS → Owner's phone + Manager's phone

5. Combination Targeting​

Mix multiple targeting types.

Example:

"Send daily reports to:"
- Role: owner + admin
- Group: Finance Team
- Ad-hoc: accountant@firm.com

6. Recipient Preview​

See who will receive before saving.

Feature: Preview API endpoint shows resolved recipients list with source attribution.

7. Audit Trail​

Log who was selected and why.

Feature: communication_recipient_log table tracks every recipient selection with source information.

Architecture Summary​

New Tables (4)​

  1. communication_recipient_group - Custom groups businesses create
  2. communication_group_member - Members in groups (users, emails, phones)
  3. business_communication_recipient_rule - Rules for who receives what
  4. communication_recipient_log - Audit trail of selections

Key Services​

  1. RecipientResolverService - Core logic to resolve rules to recipients
  2. RecipientGroupsService - Manage groups and members
  3. RecipientRulesService - Manage targeting rules

Data Flow​

Event → Handler → RecipientResolverService → Query Rules → Resolve Recipients
                                                ↓
                                    For each rule type:
                                    • role → query users
                                    • group → query members
                                    • ad_hoc → use directly
                                                ↓
                                    Deduplicate → Return list
                                                ↓
                                    Send + Log

Getting Started​

Phase 1: Review Documentation (1-2 days)​

  • Read proposal summary
  • Review architecture design
  • Understand ERD and data model
  • Review implementation checklist

Phase 2: Approve & Plan (1 day)​

  • Get stakeholder approval
  • Create Jira tickets from checklist
  • Assign ownership
  • Schedule sprints

Phase 3: Database Setup (1 day)​

  • Review migration file
  • Test in development
  • Run in staging
  • Run in production

Phase 4: Backend Implementation (10-14 days)​

  • Repositories
  • Services (especially RecipientResolverService)
  • APIs
  • Update handlers
  • Tests

Phase 5: Frontend Implementation (5-7 days)​

  • Group management UI
  • Rule configuration UI
  • Integration with settings

Phase 6: Testing & Deployment (3-4 days)​

  • Comprehensive testing
  • Staging deployment
  • Production deployment
  • Monitoring

Total: 4-6 weeks

Real-World Examples​

Example 1: Restaurant Chain​

Requirement: "Send low stock alerts for perishables to our supply manager + 2 external vendors"

Configuration:

Rules for low_stock_alert (email):
1. Role: supply_manager
2. Ad-hoc: vendor1@produce.com
3. Ad-hoc: vendor2@meats.com

Example 2: Retail Store​

Requirement: "Send daily sales reports to owner + 'Finance Team' (accountant + 2 managers + external CPA)"

Configuration:

Finance Team group:
- accountant (business_user)
- manager1 (business_user)
- manager2 (business_user)
- cpa@firm.com (email)

Rules for daily_report (email):
1. Role: owner
2. Group: Finance Team

Example 3: Multi-Location Business​

Requirement: "Emergency alerts via SMS to all owners, all admins, and security service"

Configuration:

Rules for emergency_alert (sms):
1. Role: owner
2. Role: admin
3. Ad-hoc: +1-555-SECURITY

Success Criteria​

Functional​

  • ✅ 100% of communication types support recipient targeting
  • ✅ Zero code changes needed to modify recipients
  • ✅ External contacts can receive communications
  • ✅ Multiple targeting types can be combined
  • ✅ Complete audit trail

Performance​

  • ✅ Recipient resolution < 500ms
  • ✅ No impact on communication send time
  • ✅ Database queries optimized

Usability​

  • ✅ Admin UI is intuitive
  • ✅ Preview feature works
  • ✅ 80% of businesses use custom groups within 1 month

Questions?​

Technical Questions​

Contact: Backend team lead

Product Questions​

Contact: Product manager

Implementation Questions​

Refer to: Implementation Checklist

Version History​

VersionDateChanges
1.02025-10-26Initial proposal and design

Appendix: Quick Reference​

Rule Types​

TypeUse WhenExample
roleAll users with specific roleAll inventory managers
groupSpecific team/departmentFinance Team
ad_hoc_emailSingle external emailsupplier@vendor.com
ad_hoc_phoneSingle phone number+1234567890
ad_hoc_whatsappSingle WhatsApp+1234567890

Member Types​

TypeUse WhenExample
business_userInternal employeeJohn Doe (user)
emailExternal email contactaccountant@firm.com
phonePhone for SMS+1234567890
whatsappWhatsApp number+1234567890

Communication Types (Examples)​

  • low_stock_alert
  • daily_report
  • invoice
  • collection_notice
  • emergency_alert
  • invitation

Channels​

  • email
  • sms
  • whatsapp
  • messenger