Pulses Management

The Pulses Management submodule handles project pulse tracking, communication updates, and automated status monitoring within the admin projects system.

🎯 Overview

This submodule manages project pulses - automated and manual check-ins that track project health, client satisfaction, communication patterns, and milestone progression.

🔧 Service Methods

Core Pulse Operations

getPulses()

Retrieves project pulses with filtering, pagination, and comprehensive data aggregation.

Key Features:

• Advanced filtering by status, type, and date ranges
• Pagination support for large pulse datasets
• Account and subscription-based filtering
• Role-based data access control

getPulse()

Retrieves detailed information for a specific project pulse including communication history.

Key Features:

• Complete pulse data aggregation
• Communication thread integration
• Status history and timeline tracking
• Related task and order information

createPulse()

Creates new project pulses with automated assignment and notification triggers.

Key Features:

• Pulse creation with business rule validation
• Automatic team assignment and routing
• Pulse type-specific configuration
• Integration with notification system

updatePulse()

Updates existing pulse information, status, and associated metadata.

Key Features:

• Pulse modification with validation
• Status progression management
• Activity logging and audit trails
• Automated workflow triggers

updatePulseCommunication()

Updates pulse communication records and manages conversation threading.

Key Features:

• Communication update with threading
• Notification triggers for stakeholders
• File attachment management
• Activity tracking integration

🔐 Authorization Framework

Role Requirements

All pulse operations require appropriate PROJECT_ROLES permissions:

• Admin: Full pulse management and analytics access
• Account Manager: Account-specific pulse oversight
• Fulfillment Specialist: Pulse execution and updates
• Team Lead: Team-based pulse coordination

Permission Validation

• Pulse Access: Validates user access to specific pulses
• Modification Rights: Ensures proper permissions for updates
• Communication Access: Role-based filtering of pulse communications
• Creation Authority: Validates pulse creation permissions

🏗️ Technical Architecture

Database Collections

• _projects-pulse: Core pulse data and status tracking
• _projects-tasks: Related task and workflow integration
• _store.orders: Order and subscription context
• _communications: Pulse communication and messaging
• _accounts: Account relationship and access control

Pulse Types

The service supports various automated pulse types:

• Account Churn Rate: Monitors account retention metrics
• Schedule Onboarding: Tracks onboarding milestone completion
• Upsell Opportunity: Identifies expansion opportunities
• Support Request Escalation: Manages support escalation workflows
• Inactive Task Handler: Monitors task completion rates
• Subscription Inquiry Handler: Manages subscription-related queries
• Loyalty Milestone Handler: Tracks client loyalty milestones
• Review Request Handler: Manages review collection processes
• Quarterly Check-in Pulse: Scheduled client health checks
• Payment Failure Handler: Manages payment issue resolution

Workflow Integration

• Age Filtering: Uses addPulseAgeFilter for time-based queries
• Type Filtering: Uses handlePulseTypeFilter for pulse categorization
• Activity Logging: Comprehensive audit trail integration
• Socket Integration: Real-time pulse updates and notifications

📊 Pulse Analytics

Automated Pulse Generation

The system automatically generates pulses based on:

• Account Health Metrics: Churn risk and engagement levels
• Project Milestones: Completion rates and timeline adherence
• Communication Patterns: Response times and interaction frequency
• Payment Status: Billing issues and subscription health
• Support Metrics: Ticket volumes and resolution times

Pulse Categorization

• Health Check Pulses: Regular account and project health monitoring
• Milestone Pulses: Project completion and progress tracking
• Risk Assessment Pulses: Churn risk and retention monitoring
• Opportunity Pulses: Upsell and expansion identification
• Issue Resolution Pulses: Problem identification and resolution

🔄 Integration Points

External Systems

• Communication System: Message threading and notification delivery
• Analytics System: Pulse metrics and performance tracking
• Notification System: Real-time and scheduled notifications
• Activity System: Comprehensive audit trail integration

Internal Services

• Order Management: Integration with subscription and order data
• Task Management: Related task and workflow coordination
• User Management: Team assignment and role validation
• Account Management: Account relationship and access control

📈 Business Logic

Pulse Lifecycle

graph TD
    A[Pulse Trigger] --> B[Pulse Creation]
    B --> C[Team Assignment]
    C --> D[Processing & Updates]
    D --> E{Resolution Required?}
    E -->|Yes| F[Resolution Workflow]
    E -->|No| G[Status Update]
    F --> H[Completion]
    G --> H

Automated Pulse Rules

• Churn Prevention: Early warning system for at-risk accounts
• Milestone Tracking: Automated progress monitoring and alerts
• Quality Assurance: Regular check-ins for service quality
• Opportunity Identification: Automated upsell and expansion alerts

🛡️ Security Features

Data Protection

• Input Validation: Comprehensive input sanitization and validation
• Role-based Access: Granular permission checking for all operations
• Audit Logging: Complete audit trails for compliance and tracking
• Communication Security: Secure pulse conversation management

Authorization Checks

• Pulse Access: Validates user access to specific pulses
• Modification Rights: Ensures proper permissions for updates
• Communication Rights: Role-based filtering of pulse communications
• Team Access: Validates team-based pulse assignment and access

📝 Usage Examples

Creating a Health Check Pulse

await createPulse({
  accountId: 'acc_123',
  type: 'health_check',
  title: 'Quarterly Account Review',
  description: 'Regular account health assessment',
  dashclicks: userRoles,
});

Updating Pulse Status

await updatePulse({
  pulseId: 'pulse_456',
  status: 'in_progress',
  assignedTeam: 'team_abc',
  dashclicks: userRoles,
});

Managing Pulse Communications

await updatePulseCommunication({
  pulseId: 'pulse_456',
  communication: {
    message: 'Client responded positively',
    attachments: ['response.pdf'],
  },
  dashclicks: userRoles,
});

⚠️ Important Notes

• Automated Generation: Many pulses are automatically generated based on system triggers
• Team Assignment: Pulses are automatically assigned to appropriate teams based on type
• Status Progression: Pulse status updates follow defined workflow rules
• Communication Threading: All pulse communications maintain proper conversation threading
• Role Dependencies: Operations require appropriate PROJECT_ROLES permissions
• Activity Tracking: All pulse operations generate comprehensive audit trail entries
• Integration Dependencies: Pulses integrate with multiple system components for comprehensive monitoring