Skip to main content

LLD: Fetch Revenue Trend API

1. Overview​

Returns a TC's revenue parameters across multiple months. Used to render the Revenue Parameters bar chart on the TC detail page.

The chart has a dropdown to switch between 6 parameters:

  • ARR — revenueParams.arr
  • AT & C — revenueParams.atc
  • Demand — revenueParams.demand
  • Collection — revenueParams.collection
  • Billing efficiency — revenueParams.billingEfficiency
  • Collection efficiency — revenueParams.collectionEfficiency

Each shows a bar chart with months on the X-axis and the selected parameter's value on the Y-axis.

2. Endpoint​

RouteMethod
GET /audit/transformers/:id/revenue-trendGET

Single route — user type (Admin vs AE) resolved from request.user.userType. AE users are validated against their assigned section.

3. Request​

3.1 Headers​

HeaderRequiredDescription
AuthorizationYesBearer <sessionToken>

3.2 Path Parameters​

ParamTypeRequiredDescription
idstringYesThe id field of the transformer document (e.g., TC-xxx)

3.3 Query Parameters​

ParamTypeRequiredDefaultDescription
monthstringNoCurrent month (YYYY-MM)End month of the trend window (inclusive)
monthsintegerNo6Number of months to include (1–12). Window is [month - (months-1), month]

4. Response​

4.1 Success (200)​

{
  "success": true,
  "message": "Revenue trend fetched successfully",
  "data": {
    "trend": [
      {
        "month": "2025-09",
        "revenueParams": {
          "arr": 320000,
          "atc": 290000,
          "demand": 310000,
          "collection": 300000,
          "billingEfficiency": 94,
          "collectionEfficiency": 88
        }
      },
      {
        "month": "2025-10",
        "revenueParams": {
          "arr": 500000,
          "atc": 450000,
          "demand": 480000,
          "collection": 460000,
          "billingEfficiency": 96,
          "collectionEfficiency": 92
        }
      }
    ]
  }
}

Notes:

  • Array is sorted by month ascending.
  • Missing months are omitted (no backfill).
  • Individual revenueParams fields may be null if not computed for that month.
  • The frontend selects which field to chart based on the dropdown value.

4.2 Not Found (404)​

{
  "success": false,
  "message": "Transformer not found"
}

4.3 Forbidden (403)​

{
  "success": false,
  "message": "TC does not belong to your assigned section"
}

5. Business Logic​

Identical to fetchConsumptionTrend — only the projection differs.

5.1 Compute Month Window​

endMonth = month param (or current month if not provided)
numberOfMonths = months param (or 6 if not provided)
startMonth = endMonth - (numberOfMonths - 1) months

5.2 Validate TC Exists​

const transformer = await transformerModel
  .findOne(
    { id: params.id, month: endMonth },
    { _id: 0, id: 1, "location.sectionCode": 1 }
  )
  .lean();

if (!transformer) {
  return 404 — "Transformer not found";
}

5.3 AE Section Validation​

Same as fetchConsumptionTrend / fetchTransformerDetail.

5.4 Fetch Trend Data​

const trend = await transformerModel
  .find(
    {
      id: params.id,
      month: { $gte: startMonth, $lte: endMonth },
    },
    {
      _id: 0,
      month: 1,
      "revenueParams.arr": 1,
      "revenueParams.atc": 1,
      "revenueParams.demand": 1,
      "revenueParams.collection": 1,
      "revenueParams.billingEfficiency": 1,
      "revenueParams.collectionEfficiency": 1,
    },
  )
  .sort({ month: 1 })
  .lean();

6. Validation Schema (AJV)​

6.1 Path Parameters Schema​

{
  type: "object",
  properties: {
    id: { type: "string", transform: ["trim"] }
  },
  required: ["id"]
}

6.2 Query String Schema​

Same as fetchConsumptionTrend.

6.3 Response Serialization​

{
  type: "object",
  properties: {
    trend: {
      type: "array",
      items: {
        type: "object",
        properties: {
          month: { type: "string" },
          revenueParams: {
            type: "object",
            properties: {
              arr: { type: ["number", "null"] },
              atc: { type: ["number", "null"] },
              demand: { type: ["number", "null"] },
              collection: { type: ["number", "null"] },
              billingEfficiency: { type: ["number", "null"] },
              collectionEfficiency: { type: ["number", "null"] },
            },
          },
        },
      },
    },
  },
}

7. Route Config​

{
  routeId: "fetchRevenueTrend",
  authentication: {},
  authorization: { action: "read", resource: "audit" }
}

8. File Structure​

api/src/entities/audit/
  audit.route.v1.js                     — Add new route entry
  controller/
    fetchConsumptionTrend.js            — Existing (graph 1)
    fetchRevenueTrend.js                — New (graph 2)

9. Error Handling​

Same as fetchConsumptionTrend.

10. Performance Notes​

  • Same as fetchConsumptionTrend — 2 reads (3 for AE).
  • Response slightly larger (6 fields per month vs 2) but still tiny (≤12 objects).