ACM (Account Client Management)

The Admin ACM module provides subscription analytics, team management, and client relationship administration within the DashClicks platform.

📋 ACM Submodules

Core ACM Management

• ACM Analytics - Subscription analytics, performance metrics, and filtering operations
• Client Management - Subscription assignments and client relationship management
• Team Operations - Team management and user assignment operations

🏗️ Architecture Overview

• Location: internal/api/v1/admin/routes/acm.route.js
• Service: internal/api/v1/admin/services/acm.service.js
• Controller: internal/api/v1/admin/controllers/acm.controller.js
• Route Prefix: /v1/admin/acm
• Authorization: DashClicks staff with ACM management permissions

📊 Module Statistics

Submodule	Key Features
ACM Analytics	Analytics, filtering, subscription metrics
Client Management	Subscription assignments, client relationships
Team Operations	Team management, user coordination

🚀 Key Administrative Features

Subscription Analytics

• MRR Analysis: Monthly Recurring Revenue tracking and analytics
• Subscription Metrics: New subscriptions, cancellations, churn, and retention analytics
• Product Analytics: Product-specific performance and revenue analysis
• Date Range Analytics: Flexible date range analysis with trend comparison

Team Assignment Management

• Subscription Assignment: Assign subscriptions to specialists, team leads, and managers
• Role-based Access: Role validation for subscription assignments
• Team Coordination: Multi-role team assignment and collaboration
• Workload Distribution: Team member workload tracking and optimization

Administrative Controls

• Filter Management: Dynamic filtering for analytics and subscription management
• Team Operations: Team creation, updates, and member management
• User Management: User role updates and ACM permission management
• Audit Logging: Comprehensive logging of all ACM operations

🔧 Service Methods & Business Logic

Core Analytics Services

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

• Business Logic: Processes complex subscription analytics across multiple dimensions with automatic period-over-period comparison
• Key Features:
  • Multi-type Analytics: Supports MRR, ASL, RET, EXP, NEW, CAN, CHR, RATE, CANBD analytics simultaneously
  • Date Range Processing: Automatically calculates comparison periods (current vs previous) for trend analysis
  • Price Normalization: Converts different billing intervals (daily, weekly, monthly, yearly) to standardized monthly amounts
  • Advanced Filtering: Filters by products, team assignments, project status, and assignment status
  • Parallel Processing: Uses Promise.allSettled for concurrent execution of multiple analytics types
• MongoDB Collections: stripe.subscriptions, _store.subscriptions, _store.orders
• Returns: Structured analytics data with comparison metrics and trend analysis

queryFilters({ filters, accId })

• Business Logic: Dynamically generates available filtering options based on user permissions and account context
• Key Features:
  • Role-based Filtering: Returns only users with allowed ACM roles (specialist, team_lead, manager)
  • Product Counts: Aggregates subscription counts by product type for filter options
  • User Assignment Counts: Counts subscriptions assigned to each team member
  • Status Analytics: Provides counts for project statuses, unassigned, and trialing subscriptions
  • Permission Context: Filters based on user's department access and role permissions
• MongoDB Collections: _users, stripe.subscriptions
• Returns: Filter options with counts for dynamic 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 advanced filtering, pagination, and sorting capabilities
• Key Features:
  • Advanced Pagination: Efficient pagination for large subscription datasets
  • Multi-field Sorting: Supports sorting by creation date, amount, account names, product names, status
  • Account Hierarchy: Properly handles main account vs sub-account relationships
  • Assignment Status: Filters by assigned vs unassigned subscriptions
  • Trial Status: Separates trialing subscriptions from active subscriptions
  • Cancellation Data: Includes feedback data for cancelled subscriptions
• MongoDB Collections: stripe.subscriptions, _accounts, _store.products, _store.subscriptions.feedback
• Returns: Paginated subscription data with account information and assignment details

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

• Business Logic: Assigns subscriptions to team members with comprehensive validation and role checking
• Key Features:
  • Role Validation: Ensures user has appropriate ACM role for assignment
  • Cross-role Assignment: Allows managers to assign as specialists, team leads to assign as specialists
  • Business Rule Enforcement: Validates subscription exists and is assignable
  • Socket Notifications: Emits real-time notifications for subscription assignments
  • Audit Trail: Maintains comprehensive assignment history and changes
  • Multi-role Updates: Can assign specialist, team_lead, and manager roles simultaneously
• MongoDB Collections: stripe.subscriptions, _store.subscriptions, _store.orders, _users
• Returns: Updated subscription with assignment details

Team Management Services

getTeams({ accId, isOwner, dashclicks })

• Business Logic: Retrieves team information with member details and organizational structure
• Key Features:
  • Permission Validation: Ensures user has appropriate access to team information
  • Team Hierarchy: Provides complete team structure and member relationships
  • Role Context: Includes team member roles and ACM permissions
  • Account Scoping: Filters teams by account boundaries and access rights
• MongoDB Collections: admin.teams, _users
• Returns: Team structure with member details and role information

updateTeam({ isOwner, dashclicks, userIds, teamName, operation })

• Business Logic: Updates team membership with add/remove operations and role validation
• Key Features:
  • Operation Types: Supports 'add' and 'remove' operations for team members
  • Role Validation: Ensures user has permission to modify team structure
  • Bulk Operations: Can add/remove multiple users in single operation
  • Team Integrity: Maintains team structure and prevents orphaned assignments
• MongoDB Collections: admin.teams
• Returns: Updated team structure with operation results

User Management Services

getUsers({ accId, isOwner, dashclicks })

• Business Logic: Retrieves user information within ACM context with role-based filtering
• Key Features:
  • ACM Role Filtering: Shows only users with ACM-related roles and permissions
  • Team Integration: Includes team membership and assignment information
  • Permission Context: Respects user's access level and account boundaries
  • Profile Data: Includes user profile information and images
• MongoDB Collections: _users, admin.teams
• Returns: User list with ACM roles, team memberships, and profile data

updateUser({ accId, userId, role, isOwner, dashclicks, enabled })

• Business Logic: Updates user ACM roles and permissions with validation
• Key Features:
  • Role Assignment: Updates user's ACM role (specialist, team_lead, manager)
  • Permission Validation: Ensures requesting user has authority to modify roles
  • Enable/Disable: Can enable or disable user's ACM access
  • Cascading Updates: Updates related team assignments and subscription assignments
• MongoDB Collections: _users
• Returns: Updated user with new ACM role and permissions

Authorization Framework

• DashClicks Staff Only: All operations restricted to verified administrative staff
• Role-based Access: Granular permissions based on ACM roles (specialist, team_lead, manager)
• Multi-tenant Support: Account-based access control and data segmentation
• Audit Logging: Comprehensive logging of all ACM administrative actions

Data Management

• MongoDB Integration: Optimized aggregation pipelines for subscription analytics
• Real-time Processing: Live analytics and filtering capabilities
• Complex Filtering: Multi-dimensional filtering across products, teams, and dates
• Performance Optimization: Efficient queries for large subscription datasets

🔍 Quick Reference

Common ACM Operations

Operation	Submodule	Key Endpoints
Get Analytics	ACM Analytics	GET /v1/admin/acm/analytics
Get Subscriptions	Client Management	GET /v1/admin/acm/subscriptions
Get Filters	ACM Analytics	GET /v1/admin/acm/filters
Assign Subscription	Client Management	PUT /v1/admin/acm/assign
Get Teams	Team Operations	GET /v1/admin/acm/teams
Update Team	Team Operations	PUT /v1/admin/acm/teams

Authentication Requirements

All ACM endpoints require:

• Valid DashClicks staff authentication
• ACM management permissions based on role
• Appropriate role-based access validation (specialist, team_lead, manager)

🔗 Integration Points

The Admin ACM module integrates with:

• Subscription System: Core subscription management and Stripe integration
• Team Management: Internal team coordination and role assignments
• Analytics System: Platform-wide analytics and reporting integration
• Account Management: Account hierarchy and parent account relationships
• User Management: User role management and ACM permissions

📝 Usage Notes

• All ACM operations require DashClicks staff authentication
• Subscription assignments are validated against user roles and capabilities
• Analytics support complex filtering across multiple dimensions
• Team operations include deprecated methods (createTeam, deleteTeam)
• Real-time analytics processing for immediate insights
• Multi-tenant access control based on account hierarchy
• Comprehensive audit logging for all administrative actions