Platform Analytics

Platform Analytics provides comprehensive insights into account growth, user acquisition, subscriber metrics, and churn analysis for administrative reporting and business intelligence.

API Endpoints Overview

Method	Endpoint	Description
GET	/v1/admin/analytics/platform/accounts	Account growth analytics
GET	/v1/admin/analytics/platform/users	User growth analytics
GET	/v1/admin/analytics/platform/new-subscribers	New subscriber analytics
GET	/v1/admin/analytics/platform/total-active-paying-accounts	Active paying account metrics
GET	/v1/admin/analytics/platform/accounts-churn	Account churn analytics

Service Methods & Business Logic

Account Growth Analytics

getAccounts(startDate, endDate) - Account growth tracking

• Retrieves account creation analytics with date range filtering
• Calculates growth rate comparing current period to previous period of same duration
• Filters active accounts created within specified date range
• Returns time-series data with total count and growth rate percentage
• MongoDB Collections: _accounts
• Key Filters: { active: true, created_at: { $gte: startDate, $lte: endDate } }

User Growth Analytics

getUsers(startDate, endDate) - User acquisition tracking

• Retrieves user creation analytics with date range filtering
• Calculates user growth rate comparing periods
• Analyzes all user registrations within specified timeframe
• Returns user growth data with current total and growth percentage
• MongoDB Collections: crm.contacts (users collection)
• Key Filters: { created_at: { $gte: startDate, $lte: endDate } }

New Subscriber Analytics

newSubscribers(startDate, endDate) - New subscription tracking

• Retrieves new subscriber analytics for software products with tier filtering
• Filters active subscriptions for tier1, tier2, tier3 products
• Calculates subscriber growth rate with historical comparison
• Returns comprehensive new subscriber data with growth metrics
• MongoDB Collections: _store.subscriptions, _store.prices, _store.products
• Key Filters:
  • { status: 'active', created_at: { $gte: startDate, $lte: endDate } }
  • { 'product.metadata.product_type': 'software' }
  • { 'price.metadata.tier': { $in: ['tier1', 'tier2', 'tier3'] } }

Active Paying Accounts Analytics

totalActivePayingAccounts(startDate, endDate) - Active account tracking

• Retrieves active paying account analytics with subscription validation
• Filters accounts with active subscriptions created in date range
• Calculates growth rate for paying account acquisition
• Returns paying account metrics with growth analysis
• MongoDB Collections: _accounts, _store.subscriptions
• Key Filters:
  • { active: true, created_at: { $gte: startDate, $lte: endDate } }
  • { 'subscriptions.status': 'active' }

Account Churn Analytics

accountsChurn(startDate, endDate) - Churn rate calculation

• Calculates account churn rate using industry-standard formula
• Tracks canceled subscriptions within specified period
• Compares active subscribers at period beginning plus new subscribers
• Churn Rate Formula: (Canceled Accounts) / (Active at Start + New Subscribers) * 100
• Returns churn rate percentage with supporting data
• MongoDB Collections: _accounts, _store.subscriptions
• Key Filters: { 'subscriptions.status': 'canceled', 'subscriptions.updated_at': { $gte: startDate, $lte: endDate } }

Technical Implementation Details

Date Range Processing

const getDateValues = ({ startDate, endDate }) => {
  // Default to last 30 days if no dates provided
  if (!startDate && !endDate) {
    startDate = moment().add(-30, 'days');
    endDate = moment();
  }

  const dayDifference = endDate.clone().diff(startDate, 'days');
  const previousEndDate = startDate.clone();
  const previousStartDate = startDate.clone().add(-dayDifference, 'days');

  return { sDate: startDate, eDate: endDate, previousEndDate, previousStartDate };
};

Growth Rate Calculation

// Standard growth rate calculation: ((present - past) / past) * 100
const growthRate = {
  $ifNull: [
    {
      $trunc: [
        {
          $multiply: [
            {
              $divide: [
                {
                  $subtract: [currentValue, previousValue],
                },
                previousValue,
              ],
            },
            100,
          ],
        },
        2, // Truncate to 2 decimal places
      ],
    },
    0,
  ],
};

MongoDB Aggregation Pipeline Pattern

const aggregationPipeline = [
  {
    $facet: {
      currentData: [{ $match: currentPeriodFilters }, ...countByCreatedAtQuery],
      previousCount: [{ $match: previousPeriodFilters }, { $count: 'total' }],
    },
  },
  {
    $set: {
      growthRate: growthRateCalculation,
    },
  },
];

API Response Format

Standard Analytics Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "currentData": {
      "total": 1250,
      "data": [
        {
          "date": "2024-10-01T00:00:00.000Z",
          "count": 45
        },
        {
          "date": "2024-10-02T00:00:00.000Z",
          "count": 52
        }
      ]
    },
    "growthRate": 15.75
  }
}

Churn Analytics Response

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "currentAccountChurnData": {
      "total": 23,
      "data": [...]
    },
    "churnRate": 2.85,
    "activeSubscriberCountAtBegining": 800,
    "newSubscribers": 45
  }
}

Business Logic Workflows

Account Growth Analysis Flow

graph TD
    A[Analytics Request] --> B[Process Date Range]
    B --> C[Query Current Period Accounts]
    B --> D[Query Previous Period Accounts]
    C --> E[Calculate Growth Rate]
    D --> E
    E --> F[Format Response Data]
    F --> G[Return Analytics Response]

    subgraph "Data Processing"
        H[Filter Active Accounts]
        I[Group by Creation Date]
        J[Count Totals]
        K[Compare Periods]
    end

    C --> H --> I --> J --> E
    D --> J --> K --> E

Churn Rate Calculation Flow

graph TD
    A[Churn Analysis Request] --> B[Get Active Subscribers at Period Start]
    A --> C[Get New Subscribers in Period]
    A --> D[Get Canceled Subscriptions in Period]

    B --> E[Calculate Churn Rate]
    C --> E
    D --> E

    E --> F[Churn Rate = Canceled / (Active Start + New) * 100]
    F --> G[Return Churn Analytics]

Query Parameters

Common Parameters

• start_date (ISO string, optional) - Analytics period start date
• end_date (ISO string, optional) - Analytics period end date

Default Behavior

• If no dates provided, defaults to last 30 days
• Previous period is calculated as same duration before start date
• All dates processed in UTC timezone using moment.js

Authorization & Access Control

DashClicks Staff Authentication

• All platform analytics endpoints require adminAppCheck('analytics') middleware
• Restricted to verified DashClicks staff members only
• No account-level or user-level access permitted

Rate Limiting

• validateLimit middleware applied to all endpoints
• Standard API rate limiting for administrative functions
• Audit logging for all analytics access

Error Handling

Common Error Scenarios

• Invalid date format parameters
• Insufficient permissions (non-staff access)
• Database connection issues
• Rate limit exceeded

Error Response Format

{
  "success": false,
  "message": "ERROR_MESSAGE",
  "errno": 400
}

Performance Considerations

Database Optimization

• Indexes on created_at fields for efficient date range queries
• Aggregation pipeline optimization for large datasets
• Connection pooling for concurrent analytics requests

Caching Strategy

• Results can be cached for recent periods to improve performance
• Cache invalidation based on data update frequency
• Consider implementing Redis caching for frequently accessed metrics

Usage Examples

Get Account Growth for Last 30 Days

GET /v1/admin/analytics/platform/accounts
Authorization: Bearer {admin_token}

Get User Growth for Specific Period

GET /v1/admin/analytics/platform/users?start_date=2024-09-01&end_date=2024-09-30
Authorization: Bearer {admin_token}

Get Churn Analytics

GET /v1/admin/analytics/platform/accounts-churn?start_date=2024-09-01&end_date=2024-09-30
Authorization: Bearer {admin_token}