---
feature: Main dashboard
slug: dashboard
surface: admin
consumer: react
version: 1.0.0
status: ready
brd_version: "1.3"
brd_ids: [ADMIN-002]
business_rules: [BR-24, BR-25, BR-29]
decisions: [DEC-20, TD-27, TD-161]
schema_tables: [customers, providers, drivers, orders, trips, payments, refunds, wallets, wallet_transactions, earnings, payouts, provider_subscriptions]
related_docs: [reports.md, auth.md]
last_updated: 2026-11-02
---

# Main dashboard — React Dashboard Integration Guide

> **Base URL:** `{HOST}/api/v1/admin` · Shared rules (headers, envelope, errors,
> pagination, axios setup, TS types): [API_CONVENTIONS.md](../API_CONVENTIONS.md)

## Version history

Newest first. Never edit an old row.

| Version | Date | Type | Summary | Dashboard action required |
|---------|------|------|---------|---------------------------|
| 1.0.0 | 2026-11-02 | MAJOR | `GET /dashboard` returns the BRD summary (accounts, orders, trips, payments, refunds, wallet, commissions, transport fees, amounts due, featured subscriptions); the `users` block is removed. | Replace the home widgets with the new blocks; drop `data.users`. |
| 0.2.0 | 2026-10-27 | MINOR | `system` block (server PHP/Laravel versions and environment) removed from response. | Remove references to `data.system` or make optional; rely only on `data.users`. |
| 0.1.0 | 2026-10-21 | Initial (base) | Documents `GET /dashboard` with a real response. | Optional placeholder home; the payload will change in 1.0.0. |

## Changelog

### 1.0.0 — 2026-11-02

- **Changed (breaking):** `GET /dashboard` returns the ADMIN-002 summary: the same object as `GET /reports/summary` with no window ([reports](reports.md) §3.1 lists every key). `data.users` (`total`, `active`, `today`, `this_week`) is removed.
- **Migration:** old `users.total` ≈ `accounts.customers.total + accounts.providers.total + accounts.drivers.total` (admins are not counted). Status moves from `base (TD-32)` to `ready`.
- **BRD / decisions:** ADMIN-002, AC-ADMIN-002, TD-161.


### 0.2.0 — 2026-10-27
- **Added:** —
- **Changed:** `GET /dashboard` response data now returns only user count metrics.
- **Fixed:** —
- **Removed / Deprecated:** `system` block (`php_version`, `laravel_version`, `environment`) removed from `data`.
- **Breaking:** No (provisional 0.x; dashboard components must not access `data.system`).
- **Endpoints affected:** `GET /dashboard`
- **Dashboard action required:** Remove any UI widgets displaying server PHP/Laravel versions or environment.
- **BRD / decisions:** ADMIN-002 (partial), DEC-20, TD-32

### 0.1.0 — 2026-10-21
- **Added:** documentation for `GET /dashboard`. No code change.
- **Changed:** —
- **Fixed:** —
- **Removed / Deprecated:** —
- **Breaking:** No
- **Endpoints affected:** `GET /dashboard`
- **Dashboard action required:** none yet. Do not show the `system` block to supervisors (§13).
- **BRD / decisions:** ADMIN-002 (partial), DEC-20, TD-32

---

## 1. Business summary

Login opens the main dashboard. It summarizes the platform over all time: customers, providers, drivers; orders by outcome and type, current orders; trips and current transport requests; payments, refunds and wallet; provider and driver amounts due and commissions; active and expired featured subscriptions and their payments (ADMIN-002). It is computed by the same code as the reports, so it always reconciles with `GET /reports/summary` without a window (AC-ADMIN-002).

## 2. Pages and permissions

| Page / component | Purpose | Endpoint(s) | RBAC permission (route name) | Section · action |
|------------------|---------|-------------|------------------------------|------------------|
| HomePage | Summary widgets | `GET /dashboard` | `admin.dashboard.index` | dashboard · view |

## 3. List / table

N/A.

## 4. Details view

`GET /dashboard` — no parameters. Keys and their meaning: [reports §3.1](reports.md). Postman: `admin.dashboard.index` › "200 Dashboard All Time":

```json
{
    "status": "success",
    "message": "Dashboard metrics retrieved",
    "data": {
        "period": {
            "from": null,
            "to": null
        },
        "accounts": {
            "customers": {
                "total": 2,
                "new": 2
            },
            "providers": {
                "total": 1,
                "new": 1,
                "approved": 1
            },
            "drivers": {
                "total": 1,
                "new": 1,
                "approved": 1
            }
        },
        "orders": {
            "total": 4,
            "completed": 2,
            "cancelled": 1,
            "rejected": 0,
            "expired": 0,
            "instant": 1,
            "scheduled": 3,
            "by_kind": {
                "service": 4,
                "package_purchase": 0,
                "package_session": 0
            },
            "delayed": 1,
            "current": 1
        },
        "trips": {
            "total": 2,
            "completed": 1,
            "no_driver": 0,
            "cancelled": 0,
            "current": 1
        },
        "payments": {
            "count": 4,
            "total_amount": "435.00",
            "orders_amount": "205.00",
            "featured_amount": "230.00",
            "gateway_fees": "2.30"
        },
        "refunds": {
            "count": 1,
            "amount": "40.00"
        },
        "wallet": {
            "balances_total": "40.00",
            "transactions_count": 1,
            "credits": "40.00",
            "debits": "0.00"
        },
        "commissions": {
            "provider": "15.00",
            "driver": "2.50",
            "total": "17.50"
        },
        "transportation_fees": {
            "driver": "25.00",
            "provider_self_travel": "0.00",
            "total": "25.00"
        },
        "amounts_due": {
            "provider": {
                "due": "85.00",
                "transferred": "0.00"
            },
            "driver": {
                "due": "0.00",
                "transferred": "22.50"
            }
        },
        "featured": {
            "active": 1,
            "expired": 1,
            "revenue": "230.00"
        }
    }
}
```

## 5. Forms (create / edit)

N/A.

## 6. Actions (non-CRUD)

N/A.

## 7. Statuses and enums

N/A.

## Data model

Read-only; see [reports](reports.md).

## 8. TypeScript types

`ReportSummary` in [reports §8](reports.md) (with `period: { from: null; to: null }`).

## 9. Business rules enforced by the backend

Provider and driver money are separate figures (BR-24, BR-25). Not cached: figures are live.

## 10. Notifications triggered

None.

## 11. Integration checklist

- [ ] Replace `data.users` widgets with `accounts.*`.
- [ ] Link each widget to its page (orders, trips, payouts, featured subscriptions) or to the reports with a window.

## 12. Acceptance scenarios

AC-ADMIN-002: `ReportsTest::test_ac_admin_002_dashboard_is_the_all_time_summary`.

## 13. Open decisions and known limitations

| ID | Impact | Current behavior |
|----|--------|------------------|
| DEC-20 | Performance targets | Not defined; figures follow the BRD lists (TD-161) |