---
feature: Home indicators
slug: dashboard
surface: admin
consumer: vue
version: 0.1.1
status: in-progress
brd_version: "Morvia Project Guide"
brd_ids: [ADM-002, ADM-032]
business_rules: []
decisions: []
schema_tables: [users]
screens: []
related_docs: []
last_updated: 2026-11-15
---

# Home indicators — React Dashboard Integration Guide

> Consumer: Vue. Base URL: `{HOST}/api/v1/admin`. See [API conventions](../API_CONVENTIONS.md).

## Quick reference

| | |
|---|---|
| Version | 0.1.1 (2026-11-15); dashboard action: integrate only the four user counts; there is no `system` block. |
| Status | In progress; ADM-002 and ADM-032 remain incomplete. |
| Auth | Active account, `Authorization: Bearer {token}`; route `admin.dashboard.index` resolves to RBAC key `dashboard.index`. |

| Method | Path | Route name | Purpose |
|---|---|---|---|
| GET | `/dashboard` | `admin.dashboard.index` | The four user counts. |

**Statuses:** no status enum. **Errors:** 401 unauthenticated, 403 inactive or permission denied; no feature-specific error code. **Open decisions:** none identified. Results are cached for 60 seconds; BRD indicators and per-indicator authorization are incomplete (§13).

## 1. Business summary

The home screen should summarize operational activity and provide access to modules permitted for the admin. The existing endpoint supplies only four aggregate user counts, not the required domain indicators.

## 2. Pages and permissions

| Page / component | Purpose | Endpoint(s) | RBAC permission (route name) |
|---|---|---|---|
| Home dashboard | Display available counts | `GET /api/v1/admin/dashboard` | `admin.dashboard.index` → `dashboard.index` |

Gate the page by the route permission and module navigation by each module's own permissions. Send `Accept: application/json`, `Authorization: Bearer {token}`, and optionally `Accept-Language: en` or `ar`; `X-Correlation-ID` is optional. No body, filters, sort or query parameters are consumed.

## 3. List / table

N/A. This endpoint returns an object, not a list.

## 4. Details view

`GET /api/v1/admin/dashboard`. Real HTTP 200 response from `AdminDashboardSettingsTest` (super admin, three users of which one is active):

```json
{"status":"success","message":"Dashboard metrics retrieved","data":{"users":{"total":3,"active":1,"today":3,"this_week":3}}}
```

| Field | Type | Description |
|---|---|---|
| `status`, `message` | string | Envelope status and localized message. |
| `data.users.total` | number | Count of non-soft-deleted users, all types. |
| `data.users.active` | number | Same scope, `is_active = true`. |
| `data.users.today` | number | Created on server's current date. |
| `data.users.this_week` | number | Created since server's start of week; no explicit upper bound. |

| HTTP | `error_code` | When / dashboard behavior |
|---|---|---|
| 401 | Not established | Missing or invalid bearer token; reauthenticate. |
| 403 | Not established | Inactive account/role or permission denied; show message and restrict access. |
| 500 | Not established | Unexpected data/cache failure; show retry state. |

RBAC is enforced in every environment: an admin without the dashboard permission gets 403 (covered by `AdminDashboardSettingsTest`).

## 5. Forms (create / edit)

N/A.

## 6. Actions (non-CRUD)

N/A; refresh by requesting the endpoint again, allowing for the cache.

## 7. Statuses and enums

N/A. `active` is a count, not a status object.

## Data model

| Table | Read / write | Notes |
|---|---|---|
| `users` | read | Counts apply the User model's soft-delete scope. |

## 8. TypeScript types

```ts
export interface DashboardData {
  users: { total: number; active: number; today: number; this_week: number };
}
export interface DashboardResponse { status: string; message: string; data: DashboardData }
```

## 9. Business rules enforced by the backend

| Rule | What the backend does | What the admin sees |
|---|---|---|
| ADM-002 (partial) | Counts users and caches a shared result for 60 seconds. | Counts may lag changes and are not segmented by role or permission. |

## 10. Notifications triggered

N/A.

## 11. Integration checklist

- [ ] Gate page and module navigation by their respective permissions; handle 401/403 and loading/error states.
- [ ] Render the four available user counts; do not label them as role-specific counts.
- [ ] Treat values as potentially 60 seconds old and do not substitute them for missing indicators.
- [ ] Verify English, Arabic and RTL; hide unimplemented indicators or label them unavailable.

## 12. Acceptance scenarios

| AC ID | Scenario | Expected |
|---|---|---|
| N/A (ADM-002) | Request available home data as an authorized admin. | Four user counts; feature test asserts 200 and the exact keys. |
| N/A (ADM-002) | Admin lacks a module permission. | BRD requires corresponding indicators hidden; backend does not yet enforce this per indicator. |
| N/A (ADM-032) | Threshold-start course needs a decision. | BRD requires escalation visibility; current endpoint provides no such indicator. |

## 13. Open decisions and known limitations

| ID | Impact on this feature | Current behavior |
|---|---|---|
| ADM-002 | Home is incomplete. | No counts by trainee, independent/affiliated trainer, center or provider; no course total/review/published/rejected/completed/cancelled; package total/active/inactive; confirmed enrollments, successful payments or revenue; trainer approvals, course reviews or cancellation requests. |
| ADM-032 | Threshold-start cases needing a decision. | No count or link supplied. |
| ADM-002 | Permission-specific indicators and current data required. | Endpoint-level RBAC only; one shared 60-second cache; module links are not returned. |
| Verification | Live production data not verified. | The example comes from a feature test with factory users; it proves the shape, not production values. |

## Version history

| Version | Date | Type | Summary | Dashboard action required |
|---|---|---|---|---|
| 0.1.1 | 2026-11-15 | PATCH | The response has no `system` block (the doc listed one that was never returned); RBAC is enforced in every environment; example from a feature test. | Do not read `data.system`. |
| 0.1.0 | 2026-11-12 | Initial | Document base metrics and BRD gaps. | Integrate available fields only. |

## Changelog

### 0.1.1 — 2026-11-15

- **Fixed:** removed `data.system` (`php_version`, `laravel_version`, `environment`) from the contract: the endpoint never returned it. Removed the claim that RBAC is bypassed in local/testing. **Breaking:** No. **Dashboard action required:** none unless a screen reads `data.system`.

### 0.1.0 — 2026-11-12

- **Added:** Base dashboard contract and missing BRD indicators.
- **Changed:** —
- **Fixed:** —
- **Removed / Deprecated:** —
- **Breaking:** No
- **Endpoints affected:** `GET /api/v1/admin/dashboard`.
- **Dashboard action required:** Gate access and render only available counts.
- **BRD / decisions:** ADM-002, ADM-032.