# 04 — Dashboard

← [Back to index](README.md)

One bundled call powers the home screen.

---

## `GET /dashboard`
**Response `200` — `DashboardSnapshot`**
```json
{
  "ownerName": "د. أحمد",
  "trialDaysRemaining": 7,
  "summary": {
    "revenueTodayPiastres": 285000,
    "appointmentsToday": 14,
    "totalPatients": 67,
    "waitingNow": 2
  },
  "upcoming": [
    {
      "id": "1",
      "patientName": "محمد علي حسن",
      "scheduledAt": "2026-05-22T10:15:00Z",
      "visitType": "كشف أول",
      "status": "scheduled"
    }
  ],
  "recentPatients": [
    {
      "id": "p1",
      "fullName": "محمد علي حسن",
      "lastVisitAt": "2026-05-22T07:00:00Z",
      "diagnosisHint": "ارتفاع ضغط الدم"
    }
  ],
  "usage": {
    "whatsapp":     { "used": 142, "included": 200 },
    "sms":          { "used": 38,  "included": 100 },
    "storageBytes": { "used": 2100000000, "included": 10000000000 },
    "patients":     { "used": 67,  "included": null }
  }
}
```

### Field notes
- `trialDaysRemaining`: `null` when the clinic is on a paid plan (hides the trial banner).
- `summary.revenueTodayPiastres`: **omit or set `null` for receptionist callers** (see
  [RBAC](README.md#6-roles--permissions-rbac)).
- `summary.totalPatients`: total registered patients (not just today's new ones).
- `summary.appointmentsToday`, `summary.waitingNow`: counts.
- `upcoming[].visitType`: a display **string/label** (not the enum). `status` is an
  [AppointmentStatus](11-enums.md).
- `recentPatients[].diagnosisHint`: nullable.
- `usage`: each meter is `{ used: int, included: int|null }`; `included: null` = unlimited.
  The home screen no longer renders the usage card, but **the `usage` object must exist** so
  the payload deserializes — return zeros / `null` if metering isn't built yet.
