Reporting Controller

Source: internal/api/v1/reviews/controllers/reporting.js
Service: reporting (ratings) service
Module: Reviews

---

Overview

The Reporting controller provides analytics and statistics for reviews. It aggregates review data across platforms to show trends, ratings distribution, and performance metrics over time.

Key Capabilities

• Overall Review Statistics across all platforms
• 30-Day Rolling Metrics for recent trends
• Last Month Comparison for period-over-period analysis
• Star Rating Distribution for 30-day period
• Percentage Change calculations

---

MongoDB Collections

Collection	Operations	Purpose
reviews.*	READ	Aggregate review data for analytics

---

Service Methods

1. reporting()

Get comprehensive review analytics for an account.

Endpoint: GET /reviews/reporting

Controller Logic:

const reporting = catchAsync(async (req, res, next) => {
  const account_id = req.auth.account_id;
  const report = await ratings.reporting(account_id);

  res.json({
    success: true,
    report: {
      ...report.all,
      reviews_in_last_month: report.reviews_in_last_month,
      reviews_in_last_30_days: report.reviews_in_last_30_days,
      last_30_days_star_ratings: report.last_30_days_star_ratings,
      percentage_since_last_month: report.percentage_since_last_month,
    },
  });
});

Response:

{
  "success": true,
  "report": {
    "total_reviews": 1250,
    "average_rating": 4.6,
    "5_star": 980,
    "4_star": 180,
    "3_star": 50,
    "2_star": 25,
    "1_star": 15,
    "reviews_in_last_month": 42,
    "reviews_in_last_30_days": 45,
    "last_30_days_star_ratings": {
      "5_star": 35,
      "4_star": 7,
      "3_star": 2,
      "2_star": 1,
      "1_star": 0
    },
    "percentage_since_last_month": {
      "total": "+7.5%",
      "5_star": "+12%",
      "average_rating": "+0.2"
    },
    "platform_breakdown": {
      "google": 750,
      "facebook": 320,
      "yelp": 180
    }
  }
}

Analytics Breakdown:

1. Overall Stats (report.all):

   • Total review count across all time
   • Average rating calculation
   • Star rating distribution (1-5 stars)
   • Platform breakdown

2. Last Month (reviews_in_last_month):

   • Reviews received in previous calendar month
   • Used for month-over-month comparison

3. Last 30 Days (reviews_in_last_30_days):

   • Rolling 30-day window
   • More current than calendar month

4. 30-Day Star Distribution (last_30_days_star_ratings):

   • Breakdown of ratings in last 30 days
   • Shows recent review quality trends

5. Percentage Changes (percentage_since_last_month):

   • Growth rates compared to previous period
   • Positive/negative indicators
   • Key metrics: total reviews, 5-star %, avg rating

---

Business Logic Flow

graph TD
    A[Receive Reporting Request] --> B[Extract account_id]
    B --> C[Call ratings.reporting Service]
    C --> D[Query All Reviews]
    D --> E[Calculate Overall Stats]
    E --> F[Filter Last Month Reviews]
    F --> G[Filter Last 30 Days]
    G --> H[Aggregate Star Ratings]
    H --> I[Calculate Percentage Changes]
    I --> J[Combine All Metrics]
    J --> K[Return Report]
    K --> L[Send Response]

---

Use Cases

Dashboard Display

// Show key metrics on review dashboard
const { total_reviews, average_rating, percentage_since_last_month } = report;

Trend Analysis

// Compare current vs previous month
if (percentage_since_last_month.total > 0) {
  showPositiveTrend();
} else {
  showNegativeTrend();
}

Star Distribution Chart

// Display rating distribution
const chartData = report.last_30_days_star_ratings;
// Render bar chart or pie chart

Performance Alerts

// Alert if average rating drops
if (report.average_rating < 4.0) {
  sendAlertToManagement();
}

---

Calculation Methods

Average Rating

// Weighted average across all reviews
average_rating = (5 * star5 + 4 * star4 + 3 * star3 + 2 * star2 + 1 * star1) / total_reviews;

Percentage Change

// Month over month growth
percentage_change = ((current - previous) / previous) * 100;

30-Day Rolling Window

// Reviews in last 30 days
const thirtyDaysAgo = new Date();
thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
reviews = await Review.find({
  account_id,
  created_at: { $gte: thirtyDaysAgo },
});

---

Performance Considerations

1. Aggregation Pipeline: Uses MongoDB aggregation for efficiency
2. Caching: Consider caching report data (5-15 min TTL)
3. Index Requirements: account_id + created_at compound index
4. Large Datasets: May be slow for accounts with 10k+ reviews

---

Authorization

Authentication: Required (JWT Bearer token)

Authorization Rules:

• ✅ Account-scoped: Only returns data for account_id
• ✅ Read-only: No modifications to review data
• ❌ No cross-account access

---

Integration Points

Related Features:

• Dashboard Widget: Displays key metrics
• Email Reports: Weekly/monthly analytics emails
• Alerts: Trigger notifications on metric changes
• Export: Include in CSV/PDF exports

---

Important Notes

1. Data Freshness: Updates as reviews sync from platforms
2. Time Zones: All dates in UTC, frontend converts
3. Excluded Reviews: Hidden reviews still counted in stats
4. Platform Breakdown: Available if multiple platforms connected

---

Related Documentation

• Reviews Controller (link removed - file does not exist) - Review data source
• Config Controller - Platform connections

---

Version: 1.0
Last Updated: December 2024
Status: ✅ Production Ready