Add Daily Performance Summary REST API

[StuartFerguson]

Summary

The mobile app has a Daily Performance Summary screen and currently uses mock data. We need a REST API endpoint that returns the report data for a selected period.

Proposed Endpoint

GET /api/reports/daily-performance-summary?period={Today|Yesterday|ThisWeek|MonthToDate}

Request

Query Parameter

• period
  • Today
  • Yesterday
  • ThisWeek
  • MonthToDate

Response Shape

{
  "period": "Today",
  "fromDate": "2026-06-28T00:00:00Z",
  "toDate": "2026-06-28T23:59:59Z",
  "periodLabel": "Today",
  "metrics": [
    {
      "title": "Total transaction count",
      "value": "48",
      "description": "Processed today",
      "category": "Total"
    },
    {
      "title": "Total transaction value",
      "value": "10,250.00 KES",
      "description": "Gross value",
      "category": "Total"
    },
    {
      "title": "Successful transaction count",
      "value": "44",
      "description": "Completed successfully",
      "category": "Success"
    },
    {
      "title": "Failed transaction count",
      "value": "4",
      "description": "Could not be completed",
      "category": "Failure"
    },
    {
      "title": "Average transaction value",
      "value": "213.54 KES",
      "description": "Average across all transactions",
      "category": "Neutral"
    },
    {
      "title": "Top product",
      "value": "Mobile Topup",
      "description": "Highest volume",
      "category": "Neutral"
    }
  ],
  "drillDownTransactions": [
    {
      "reference": "TXN-00048",
      "product": "Mobile Topup",
      "status": "Success",
      "amount": "250.00 KES",
      "transactionDateTime": "2026-06-28T09:15:00Z"
    },
    {
      "reference": "TXN-00047",
      "product": "Bill Payment",
      "status": "Success",
      "amount": "1,500.00 KES",
      "transactionDateTime": "2026-06-28T08:15:00Z"
    },
    {
      "reference": "TXN-00046",
      "product": "Voucher Issue",
      "status": "Failed",
      "amount": "0.00 KES",
      "transactionDateTime": "2026-06-28T07:15:00Z"
    }
  ]
}

Metric Categories

• Neutral
• Total
• Success
• Failure

Transaction Status Values

• Success
• Failed

Backend Requirements

• Compute and return:
  • total transaction count
  • total transaction value
  • successful transaction count
  • failed transaction count
  • average transaction value
  • top product
  • recent/drill-down transactions for the selected period
• Return data in the same shape the mobile app expects
• Preserve metric ordering so the UI can render the first 4 cards correctly
• Support mock/static data initially if full backend logic is not yet available

Acceptance Criteria

• API endpoint exists and accepts period
• Response includes fromDate, toDate, periodLabel, metrics, and drillDownTransactions
• Summary metrics are returned in a stable order
• Transaction status values support success/failure display styling in the app
• Empty data sets return a valid response
• Invalid period returns a validation error

Notes

• The mobile UI currently renders the first four summary cards in a 2x2 layout, so the metrics order matters.
• The current app is string-based for display values, so this contract can return preformatted strings initially.