Revenue Analytics Engine
BI-grade revenue intelligence with 7-tab dashboard, real-time KPIs, cohort analysis, LTV modeling, revenue forecasting, tenant health scoring, and automated PDF report delivery.
The Revenue Analytics Engine provides comprehensive financial intelligence for your SaaS platform. It aggregates subscription data from all tenants into actionable KPIs, trend visualizations, and predictive models. Nightly background jobs snapshot all metrics, compute tenant health scores, and generate scheduled reports — delivering a complete BI-grade analytics suite without external tools.
KPI Overview
Eight core KPIs are calculated in real-time from subscription and payment data. Each KPI supports date range filtering, period-over-period comparison, and drill-down by edition or tenant.
| KPI | Formula | Description |
|---|---|---|
| MRR | Sum of active monthly-normalized revenue | Monthly Recurring Revenue |
| ARR | MRR × 12 | Annual Recurring Revenue |
| NRR | (Start MRR + Expansion − Contraction − Churn) / Start MRR × 100 | Net Revenue Retention % |
| ARPU | MRR / Active Subscriptions | Average Revenue Per User |
| Churn Rate | Cancelled Subs / Total Subs × 100 | Monthly subscription churn % |
| Trial→Paid | Converted Trials / Total Trials × 100 | Trial conversion rate |
| Active Subs | Count of Status=Active | Total active subscriptions |
| New Subs | Count of subs created in period | New subscriptions this period |
7-Tab Dashboard
The analytics dashboard is organized into 7 lazy-loaded tabs, each focusing on a specific analytical dimension. Tabs are rendered via React.lazy with Suspense fallbacks for optimal bundle splitting.
| Tab | Key Visualizations | Data Source |
|---|---|---|
| Overview | KPI cards, MRR sparkline, period selector | AnalyticsSummary API |
| MRR Waterfall | Stacked bar chart: New, Expansion, Contraction, Churn, Reactivation | MRR Movements API |
| Cohort Retention | Heatmap grid showing retention % by monthly cohort | Cohort API |
| LTV by Edition | Bar chart comparing lifetime value per edition tier | LTV API |
| Revenue Forecast | Line chart with 6-month linear regression + confidence bands | Forecast API |
| Health Scores | Sortable table with risk badges (Healthy/At-Risk/Critical) | Health Scores API |
| Reports | List of generated/scheduled reports with download links | Reports API |
AnalyticsSnapshot Entity
The AnalyticsSnapshot entity stores daily metric snapshots. Each night, the AnalyticsSnapshotJob creates one aggregate row (TenantId = null) and one row per active tenant. This enables historical trend analysis without querying live subscription tables.
| Field | Type | Description |
|---|---|---|
| SnapshotDate | DateTime | UTC date of the snapshot |
| TenantId | Guid? | Null = aggregate row, non-null = tenant-specific |
| Mrr | decimal(18,2) | Monthly Recurring Revenue at snapshot time |
| Arr | decimal(18,2) | Annual Recurring Revenue (MRR × 12) |
| ActiveSubscriptions | int | Count of active subscriptions |
| NewSubscriptions | int | New subscriptions in the period |
| ChurnedSubscriptions | int | Cancelled subscriptions in the period |
| TrialSubscriptions | int | Active trial subscriptions |
| ConvertedTrials | int | Trials that converted to paid |
| TotalRevenue | decimal(18,2) | Cumulative revenue collected |
Tenant Health Scoring
The TenantHealthScoreJob computes a composite health score (0–100) for each active tenant using a weighted formula that combines payment reliability, platform activity, and subscription growth signals.
Health Score = (Payment × 0.40) + (Activity × 0.30) + (Growth × 0.30)
Payment Score (0-100):
- 100 if no failed payments
- Deduct 25 per failed payment in last 30 days
- Minimum 0
Activity Score (0-100):
- Based on admin login frequency in last 30 days
- 100 = daily, 75 = weekly, 50 = biweekly, 25 = monthly, 0 = inactive
Growth Score (0-100):
- 100 if user count grew > 20%
- 75 if grew 10-20%
- 50 if stable (±10%)
- 25 if declined 10-20%
- 0 if declined > 20%
Risk Classification:
≥ 70 → Healthy (green)
40-69 → At-Risk (amber)
< 40 → Critical (red)Background Jobs Pipeline
Three background jobs run in strict sequence every night. They are fully provider-agnostic — configurable to run under Native, Hangfire, or Quartz via appsettings.json. Each job implements IAutoRegisteredJob for unified management.
| Job | Schedule | Purpose | Provider |
|---|---|---|---|
| AnalyticsSnapshotJob | Daily 3:00 AM | Captures MRR/ARR/churn/trial metrics per tenant + aggregate | Native / Hangfire / Quartz |
| TenantHealthScoreJob | Daily 4:00 AM | Computes weighted health score for every active tenant | Native / Hangfire / Quartz |
| AnalyticsReportJob | Daily 6:00 AM | Generates and emails scheduled PDF reports | Native / Hangfire / Quartz |
API Endpoints
The AnalyticsController exposes 12 endpoints under /api/v1/analytics. All endpoints require SuperAdmin role and the corresponding analytics permission.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/analytics/summary | Get analytics summary (KPI cards + period comparison) | 🔒 Required |
| GET | /api/v1/analytics/mrr-movements | Get MRR waterfall movements (new/expansion/contraction/churn/reactivation) | 🔒 Required |
| GET | /api/v1/analytics/cohort-retention | Get cohort retention heatmap data by monthly cohorts | 🔒 Required |
| GET | /api/v1/analytics/ltv-by-edition | Get lifetime value breakdown by edition tier | 🔒 Required |
| GET | /api/v1/analytics/forecast | Get 6-month revenue forecast with linear regression + confidence bands | 🔒 Required |
| GET | /api/v1/analytics/health-scores | Get tenant health scores with risk classification | 🔒 Required |
| GET | /api/v1/analytics/snapshots | Get historical daily snapshots for trend charts | 🔒 Required |
| GET | /api/v1/analytics/export/{format} | Export analytics data in specified format (csv/excel/pdf) | 🔒 Required |
| GET | /api/v1/analytics/reports | List all scheduled reports | 🔒 Required |
| POST | /api/v1/analytics/reports | Create a new scheduled report configuration | 🔒 Required |
| PUT | /api/v1/analytics/reports/{id} | Update scheduled report settings | 🔒 Required |
| DELETE | /api/v1/analytics/reports/{id} | Delete a scheduled report | 🔒 Required |
Export System
Analytics data can be exported in three formats. Each export includes the current KPI summary, MRR trends, and subscription breakdown. PDF exports include branded headers and charts.
| Format | Extension | Features |
|---|---|---|
| CSV | .csv | Comma-separated values for spreadsheet import |
| Excel | .xlsx | Multi-sheet workbook with charts and formatting |
| Branded report with KPI cards, charts, and tables |
Scheduled Reports
Administrators can configure automated report delivery. Reports are generated by the AnalyticsReportJob at 6:00 AM UTC and emailed to the configured recipients in the chosen format.
| Field | Type | Description |
|---|---|---|
| ReportName | string(200) | User-defined report name |
| Cadence | ReportCadence | Daily | Weekly | Monthly |
| Format | ExportFormat | CSV | Excel | PDF |
| Recipients | string[] | Email addresses for delivery |
| IncludeSections | string[] | Which KPI sections to include |
| IsActive | bool | Whether the scheduled report is enabled |
Permissions
Revenue Analytics uses four granular permissions that can be assigned to roles via the standard RBAC system.
| Permission | Action |
|---|---|
| analytics.view | View analytics dashboard and KPI data |
| analytics.view_health | View tenant health scores |
| analytics.export | Export analytics data (CSV/Excel/PDF) |
| analytics.manage_reports | Create, edit, delete scheduled reports |