Dashboard Module

What this module solves

Provides read-only analytics for UI dashboards: totals, category breakdown, recent transactions, wallet balances, and budget allocations.

Endpoints

• GET /api/v1/dashboard/summary
• GET /api/v1/dashboard/categories
• GET /api/v1/dashboard/transactions
• GET /api/v1/dashboard/wallets
• GET /api/v1/dashboard/allocations

Validation rules

• Date filters are parsed from query string and must be valid dates.
• transactions endpoint validates limit as a positive number.
• Date range integrity is validated in application layer (ensureValidDateRange).

Internal flow

Route	Controller	Use case/service	Repository chain	Route file trace
GET /dashboard/summary	DashboardController.getSummary	DashboardServicesImpl.getSummary	TransactionRepositoryImpl	backend/src/Presentation/Routes/DashboardRoutes.ts
GET /dashboard/categories	DashboardController.getCategoryBreakdown	DashboardServicesImpl.getCategoryBreakdown	TransactionRepositoryImpl, CategoryRepositoryImpl	backend/src/Presentation/Routes/DashboardRoutes.ts
GET /dashboard/transactions	DashboardController.getRecentTransactions	DashboardServicesImpl.getRecentTransactions	TransactionRepositoryImpl	backend/src/Presentation/Routes/DashboardRoutes.ts
GET /dashboard/wallets	DashboardController.getWalletBalances	DashboardServicesImpl.getWalletBalances	WalletRepositoryImpl, TransactionRepositoryImpl	backend/src/Presentation/Routes/DashboardRoutes.ts
GET /dashboard/allocations	DashboardController.getAllocations	DashboardServicesImpl.getAllocations	BudgetAllocationRepositoryImpl	backend/src/Presentation/Routes/DashboardRoutes.ts

Controller: backend/src/Presentation/Controllers/DashboardController.ts.

Common errors

• INVALID_PAYLOAD (400) for invalid date or limit query values.
• USER_NOT_AUTHENTICATED (401).
• DASHBOARD_* errors (500) when aggregation fails.

Testing notes

• E2E files:
  • backend/src/tests/e2e/dashboard/dashboard-summary.e2e.test.ts
  • backend/src/tests/e2e/dashboard/dashboard-categories.e2e.test.ts
  • backend/src/tests/e2e/dashboard/dashboard-wallets.e2e.test.ts

Quick snippets

1) cURL request example

curl -X GET "https://budgeti-backend.johandercampos.com/api/v1/dashboard/summary?startDate=2026-02-01&endDate=2026-02-29&walletId=wlt_123" \
  -H "Authorization: Bearer <jwt>"

2) Success JSON response example

{
  "code": "DASHBOARD_SUMMARY_READY",
  "message": "Dashboard summary generated successfully",
  "data": {
    "totalIncome": 2500,
    "totalExpenses": 1740.5,
    "balance": 759.5
  }
}

3) Common error JSON response example

{
  "code": "USER_NOT_AUTHENTICATED",
  "message": "User is not authenticated",
  "error": "User is not authenticated"
}

4) Tiny internal trace snippet

// DashboardController.getSummary
const { startDate, endDate } = parseDates(req);
const summary = await dashboardService.getSummary({
  userId: req.userId!,
  startDate,
  endDate,
  walletId: req.query.walletId as string | undefined,
  categoryId: req.query.categoryId as string | undefined,
  limit: 10,
});

return res.status(200).json({
  ...buildSuccessResponse(SuccessCodes.DASHBOARD_SUMMARY_READY),
  data: summary,
});