📊 Projects Module

🎯 Overview

The Projects module manages customer engagement, retention, and loyalty tracking through automated pulse notifications and account health monitoring. This module runs multiple parallel services that analyze account activity, track loyalty milestones, and create engagement pulses.

Module Path: queue-manager/crons/projects.js
Cron Schedule: Every 5 minutes (*/5 * * * *)
Services: 7 parallel processors
Business Impact: HIGH - Customer retention and engagement

📁 Module Structure

projects/
├── crons/
│   └── projects.js                    # Main cron orchestrator (runs all 7 services)
├── services/
│   ├── accountChurnRisk.js            # Churn probability calculation
│   ├── syncAccounts.js                # Account data synchronization
│   ├── inactiveTaskPulse.js           # Inactive task monitoring
│   ├── loyaltyMilestone.js            # Loyalty tier tracking (674 lines)
│   ├── reviewRequestPulse.js          # Review automation
│   ├── quarterlyCheckInPulse.js       # Quarterly engagement
│   └── cleanupPulses.js               # Pulse data maintenance
└── queues/
    ├── accountChurn.js                # Churn risk queue processor
    ├── inactiveTaskPulse.js           # Task pulse queue processor
    ├── reviewRequestPulse.js          # Review request queue processor
    └── quarterlycheckinpulse.js       # Check-in queue processor

🔄 Processing Flow

sequenceDiagram
    participant CRON as Cron Schedule
    participant ORCH as Projects Orchestrator
    participant SVC1 as Churn Risk Service
    participant SVC2 as Loyalty Service
    participant SVC3 as Pulse Services
    participant QUEUE as Bull Queues
    participant MONGO as MongoDB

    CRON->>ORCH: Every 5 minutes

    par Parallel Execution
        ORCH->>SVC1: calculateChurnRisk()
        SVC1->>MONGO: Query account activity
        SVC1->>QUEUE: Add churn risk jobs

        ORCH->>SVC2: loyaltyMilestone()
        SVC2->>MONGO: Query subscriptions
        SVC2->>MONGO: Create loyalty pulses

        ORCH->>SVC3: Pulse services (4 types)
        SVC3->>MONGO: Create/check pulses
        SVC3->>QUEUE: Add pulse jobs
    end

🎯 Sub-Processors

Customer Health & Retention

• 📘 Account Churn Risk - Predicts customer churn probability
• 📗 Sync Accounts - Synchronizes account data across systems
• 📙 Loyalty Milestone - Tracks MRR-based loyalty tiers (COMPLEX)

Engagement Pulses

• 📕 Inactive Task Pulse - Monitors and notifies on inactive tasks
• 📓 Review Request Pulse - Automates review requests
• 📔 Quarterly Check-In Pulse - Schedules quarterly engagements

Maintenance

• 🧹 Cleanup Pulses - Removes outdated pulse records

🗄️ Database Collections

Primary Collections

projects-pulse

• Purpose: Stores all pulse notifications (tasks, reviews, check-ins, loyalty)
• Model: models/projects-pulse.js
• Indexed Fields: account, type, status, createdAt

store-subscription

• Purpose: Subscription data for loyalty tier calculations
• Model: models/store-subscription.js
• Used By: Loyalty milestone processor

config

• Purpose: Stores loyalty program configuration with dynamic tiers
• Model: models/config.js
• Type: loyalty-program

account

• Purpose: Account data for churn risk and synchronization
• Model: models/account.js
• Used By: Churn risk, sync accounts

🔧 Environment Configuration

# Projects Module Control
QM_PROJECTS=true                    # Enable projects module

# Module Dependencies
MONGO_DB_URL=mongodb://localhost:27017/dashclicks
REDIS_HOST=localhost
REDIS_PORT=6379

🔄 Orchestrator Pattern

The projects cron uses a parallel execution pattern:

exports.start = async () => {
  cron.schedule('*/5 * * * *', async () => {
    if (!inProgress) {
      inProgress = true;
      try {
        // All services run in parallel
        await accountChurnRiskService.calculateChurnRisk();
        await syncAccountsService.syncAccounts();
        await inactiveTaskPulse.createInactiveTaskPulse();
        await inactiveTaskPulse.checkCompleteTaskAndRemovePulse();
        await loyaltyPulse.loyaltyMilestone();
        await reviewRequestPulse.reviewRequestPulse();
        await quarterlyCheckInPulseService.quarterlyCheckInPulse();
        await cleanupPulsesService.cleanupPulses();
      } finally {
        inProgress = false;
      }
    }
  });
};

📊 Pulse Types

1. Inactive Task Pulse

• Trigger: Tasks with no activity
• Action: Create notification pulse
• Cleanup: Remove when task completed

2. Review Request Pulse

• Trigger: Customer satisfaction milestones
• Action: Request product review
• Frequency: Configurable per account

3. Quarterly Check-In Pulse

• Trigger: Every 90 days
• Action: Schedule customer engagement call
• Purpose: Proactive account management

4. Loyalty Milestone Pulse

• Trigger: MRR tier changes
• Action: Celebrate customer loyalty
• Tiers: Dynamic from config (Bronze, Silver, Gold, etc.)

🚨 Error Handling

Each service has independent error handling:

try {
  await service.process();
} catch (error) {
  logger.error({
    initiator: 'QM/projects/[service]',
    error: error,
  });
}

Failures in one service don't affect others due to parallel execution.

📈 Performance Considerations

Execution Time

• Average: 2-5 seconds
• Peak: 10-15 seconds (during heavy loyalty calculations)
• Timeout: None (runs until completion)

Database Load

• Loyalty Milestone: Heaviest (aggregation queries)
• Churn Risk: Moderate (account queries)
• Pulses: Light (simple CRUD operations)

Concurrency

• All 7 services run in parallel
• Individual service locking not required
• Cron-level lock prevents overlapping executions

🔗 Related Documentation

• Account Churn Risk
• Loyalty Milestone Processor
• Pulse Management
• Queue Wrapper
• Architecture Overview (documentation unavailable)

---

Module Type: Customer Engagement
Execution: Parallel
Priority: HIGH - Affects retention and revenue