feat(analytics): implement subscription analytics suite with MRR, ARR, cohort analysis and forecasting (#724)

[primexk5]

Summary

This PR implements an advanced, enterprise-grade subscription analytics suite for SubTrackr, empowering SaaS operators and subscribers with deep visibility into Monthly Recurring Revenue (MRR), Annual Recurring Revenue (ARR), customer cohort retention curves, algorithmic revenue forecasting, customizable dashboard widgets, and multi-format report exports.

Closes #724

---

Key Highlights & Features

1. Core Analytics Service (src/services/analyticsService.ts)

   • Added period-over-period mrrGrowthRate and arrGrowthRate percentage calculations to quantify momentum.
   • Built dual algorithmic forecasting models:
     • Exponential Decay: Compounds future revenue based on historical cohort retention and natural net expansion.
     • Linear Regression: Fits an Ordinary Least Squares (OLS) trend line over observed 6-month MRR history to predict trajectories across M+1 to M+12 horizons.
   • Exported calculateRetentionCurve helper to compute Day 1, Day 7, Day 30, Day 60, and Day 90 retention milestones.

2. Analytics State & Customization Engine (app/stores/analyticsStore.ts)

   • Implemented a modular dashboard configuration store managing card visibility (enabledWidgets), layout ordering (widgetOrder), and directional reordering actions (toggleWidget, reorderWidgets, resetWidgetConfig).
   • Exposes forecastModel: 'linear' | 'exponential' state to allow real-time toggling between regression and exponential prediction algorithms.
   • Implemented multi-format summary export methods (exportSummaryCsv() and exportSummaryText()) generating clean tabular KPI reports.

3. UI Screens & Dashboard Customizer (src/components/analytics/WidgetCustomizationModal.tsx, app/screens/AnalyticsDashboard.tsx, src/screens/AnalyticsScreen.tsx)

   • Created a glassmorphic Dashboard Customizer Modal enabling users to toggle individual cards on/off, reorder dashboard layout hierarchy, and switch forecast models.
   • Added visual MoM and YoY growth rate badges (+5.2% MoM in green, -1.5% MoM in red) directly to the MRR and ARR overview cards.
   • Integrated an interactive launch banner in AnalyticsScreen.tsx connecting the general tab directly into the advanced cohort and MRR dashboard suite.

4. Backend REST API Extensions (backend/services/analytics/analyticsDashboardApi.ts)

   • Added getMrrArrReport(merchantId) exposing active MRR, ARR, ARPU, customer LTV, subscriber counts, and churn ratios.
   • Added getRevenueForecast(merchantId, model, monthsAhead) providing predictive revenue data points with statistical confidence intervals.

5. Documentation & Unit Testing (docs/analytics-guide.md)

   • Authored a comprehensive developer and user guide detailing mathematical formulas, cohort retention logic, OLS linear regression derivation, widget layout management, and REST API definitions.
   • Expanded unit test suites in analyticsService.test.ts verifying linear vs exponential regression projections, MoM growth rate accuracy, and Day 1-90 retention curve milestones.

---

Verification

• Verified that only files strictly within the analytics scope were modified or created without tampering with unrelated components.
• Verified clean TypeScript syntax and formatting across all modified files.

[drips-wave]

@primexk5 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits