Client Management

The Client Management submodule handles subscription assignments, analytics tracking, filtering coordination, and client relationship administration within the DashClicks ACM system.

🎯 Overview

This submodule manages client relationships, subscription assignments, operational filtering, and comprehensive analytics for client management optimization.

🔧 Service Methods & Business Logic

Subscription Analytics Service

queryAnalytics({ filters, startDate, endDate, types, products, specialist, team_lead, manager, unassigned, trialing })

• Business Logic: Processes complex subscription revenue and performance analytics across multiple time periods and dimensions
• Core Operations:
  1. Date Range Processing: Automatically calculates current, previous, and third comparison periods for trend analysis
  2. Parallel Analytics Execution: Uses Promise.allSettled to run multiple analytics types simultaneously (MRR, NEW, CAN, RET, etc.)
  3. Price Normalization: Converts different billing intervals to standardized monthly amounts using sophisticated adjustment algorithms
  4. Team Assignment Filtering: Filters subscriptions based on specialist, team_lead, or manager assignments
  5. Product Segmentation: Analyzes performance across different product types and service categories
• Key Analytics Types:
  • MRR (Monthly Recurring Revenue): Revenue analytics with interval normalization
  • NEW: New subscription acquisition tracking
  • CAN: Cancellation analytics with feedback integration
  • RET: Retention rate calculations and trend analysis
  • CHR: Churn rate calculations across different time periods
• MongoDB Collections: stripe.subscriptions, _store.orders, _store.subscriptions.feedback
• Returns: Multi-dimensional analytics with period-over-period comparisons

queryFilters({ filters, accId })

• Business Logic: Dynamically generates filtering options based on account context and user permissions
• Core Operations:
  1. Role-based User Aggregation: Aggregates users by ACM roles (specialist, team_lead, manager) with permission validation
  2. Product Count Analysis: Counts active subscriptions by product type for filter dropdown population
  3. Assignment Analytics: Calculates subscription counts per assigned user for workload visibility
  4. Status Categorization: Provides counts for project statuses, unassigned subscriptions, and trialing accounts
  5. Permission Filtering: Ensures users only see filter options they have access to based on department permissions
• MongoDB Aggregation Pipeline: Complex faceted aggregation across users and subscriptions
• Returns: Dynamic filter options with real-time counts for dashboard controls

Subscription Management Services

querySubscriptions({ filters, startDate, endDate, limit, page, products, specialist, team_lead, manager, sortBy, sortOrder, unassigned, trialing })

• Business Logic: Retrieves subscription data with complex filtering, sorting, and pagination for administrative management
• Core Operations:
  1. Advanced Filtering Pipeline: Constructs MongoDB aggregation pipeline with multiple filter dimensions
  2. Account Hierarchy Resolution: Handles main account vs sub-account relationships with proper parent account lookup
  3. Multi-field Sorting: Supports sorting by creation date, amount, account names, product names, and assignment status
  4. Efficient Pagination: Implements skip/limit with proper sorting for large datasets
  5. Assignment Status Integration: Shows current specialist, team_lead, and manager assignments
  6. Product Integration: Joins with store products for detailed product information
  7. Feedback Integration: For cancelled subscriptions, includes cancellation feedback and reasons
• Key Features:
  • Dynamic Sorting: Different sort strategies based on field type (database vs calculated fields)
  • Role-based Access: Filters results based on user's ACM permissions and department access
  • Trial Separation: Can filter specifically for trialing vs active subscriptions
  • Assignment Filtering: Shows only assigned, unassigned, or specific team member assignments
• MongoDB Collections: stripe.subscriptions, _accounts, _store.products, _store.subscriptions.feedback
• Returns: Paginated subscription data with complete account, product, and assignment information

assignSubscription({ filters, subscriptionId, userId, role, accountId })

• Business Logic: Assigns subscriptions to team members with comprehensive validation and business rule enforcement
• Core Operations:
  1. Role Validation: Verifies the target user has the appropriate ACM role for assignment
  2. Cross-role Assignment Logic: Allows managers to assign as specialists, team leads to assign as specialists
  3. Subscription Validation: Ensures subscription exists and is assignable
  4. Store Subscription Lookup: Validates against store subscription records for consistency
  5. Order Integration: Validates subscription has associated order record
  6. Multi-role Assignment: Can assign specialist, team_lead, and manager roles simultaneously based on assignment type
  7. Socket Notification: Emits real-time notifications to relevant team members about assignments
  8. Error Handling: Comprehensive error handling with specific error messages for different validation failures
• Business Rules:
  • Users can only be assigned roles they actually possess
  • Managers can assign subscriptions to specialists and team leads
  • Team leads can assign subscriptions to specialists
  • Super managers have expanded assignment capabilities
• Socket Integration: Emits ACM_SUBSCRIPTION_ASSIGNED events with assignment details
• MongoDB Collections: stripe.subscriptions, _store.subscriptions, _store.orders, _users
• Returns: Updated subscription record with new assignment information

🏗️ Technical Architecture

Database Collections

• _store.subscriptions: Subscription information and assignment tracking
• acm-assignments: Subscription-team member assignment relationships
• _accounts: Account hierarchy and client relationship management
• acm-analytics: Analytics data and performance metrics

Integration Systems

• Subscription System: Core subscription management and tracking integration
• Team Management: Team member assignment and role coordination
• Analytics Engine: Performance metrics collection and analysis
• Account Management: Account hierarchy and client relationship integration

Business Logic

• Assignment Logic: Complex subscription-team member assignment coordination
• Analytics Processing: Advanced analytics calculation and aggregation
• Filter Management: Dynamic filtering system with role-based access
• Performance Tracking: Client performance monitoring and optimization

🔐 Authorization Framework

Role Requirements

All client management operations require appropriate administrative permissions:

• ACM Admin: Full client management and subscription control
• Client Manager: Client relationship and subscription assignment management
• Analytics Manager: Client analytics and performance reporting access
• Team Coordinator: Team-based client assignment and coordination

Permission Validation

• Client Access: Validates access to specific client information and operations
• Assignment Authority: Ensures proper permissions for subscription assignments
• Analytics Access: Controls access to client analytics and performance data
• Multi-tenant Authorization: Account-based client access and permission validation

📊 Client Analytics

Performance Metrics

• Client Engagement: Client interaction and platform utilization analytics
• Subscription Performance: Subscription usage and effectiveness tracking
• Team Efficiency: Team member performance in client management
• Assignment Analytics: Subscription assignment success and optimization

Operational Insights

• Client Health: Client satisfaction and relationship quality tracking
• Subscription Optimization: Subscription assignment and performance optimization
• Team Performance: Team member effectiveness in client management
• Resource Allocation: Client management resource allocation and optimization

🔄 Integration Points

External Systems

• CRM Systems: Client relationship management and contact integration
• Billing Systems: Subscription billing and payment coordination
• Project Management: Client project coordination and tracking
• Communication Platforms: Client communication and support integration

Internal Services

• Account Management: Account hierarchy and client relationship integration
• Subscription System: Core subscription management and tracking
• Team Management: Team member assignment and coordination
• Analytics System: Performance metrics and reporting integration

📈 Business Workflows

Client Management Process

graph TD
    A[Client Onboarding] --> B[Subscription Assignment]
    B --> C[Team Coordination]
    C --> D[Performance Monitoring]
    D --> E[Analytics Review]
    E --> F[Optimization]

Subscription Assignment

• Assignment Process: Subscription-team member assignment with role validation
• Performance Tracking: Assignment effectiveness monitoring and optimization
• Team Coordination: Multi-role team assignment and collaboration
• Quality Assurance: Assignment quality and client satisfaction monitoring

🛡️ Security Features

Data Protection

• Client Information Security: Secure handling of client data and relationships
• Subscription Privacy: Subscription information protection and access control
• Assignment Security: Secure assignment tracking and audit trail
• Analytics Protection: Analytics data security and access control

Operational Security

• Authorization Validation: Client operation authorization and permission validation
• Data Integrity: Client data integrity and consistency maintenance
• Audit Logging: Comprehensive logging of all client management operations
• Compliance Monitoring: Client management policy compliance and adherence

📝 Usage Examples

Analytics Operations

// Retrieve ACM analytics
const analytics = await queryAnalytics({
  startDate: '2024-01-01',
  endDate: '2024-12-31',
  types: ['premium', 'standard'],
  specialist: 'user_123',
  dashclicks: adminRoles,
});

// Get available filters
const filters = await queryFilters({
  accId: accountId,
  dashclicks: managerRoles,
});

Subscription Management

// Query subscriptions with filtering
const subscriptions = await querySubscriptions({
  page: 1,
  limit: 50,
  products: ['seo', 'ppc'],
  specialist: 'user_456',
  sortBy: 'created_date',
  sortOrder: 'desc',
  dashclicks: coordinatorRoles,
});

// Assign subscription to team member
await assignSubscription({
  subscriptionId: 'sub_789',
  userId: 'user_123',
  role: 'specialist',
  dashclicks: managerRoles,
});

⚠️ Important Notes

• Multi-tenant Access: Client operations require proper account-based authorization
• Assignment Validation: Subscription assignments require role validation and business rule compliance
• Analytics Context: Analytics operations require appropriate filtering and access control
• Performance Impact: Client operations affect team performance and client satisfaction
• Data Consistency: Client management operations require careful data integrity maintenance
• Audit Requirements: All client operations require comprehensive audit trail maintenance
• Role Dependencies: Client operations require appropriate administrative permissions and team coordination