---
feature: Home indicators
slug: dashboard
surface: admin
consumer: vue
version: 0.1.0
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-12
---

# 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.0 (2026-11-12); dashboard action: integrate only the available base indicators. |
| 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` | User counts and server version information. |

**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 aggregate user counts and server information, 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 captured with an isolated in-memory SQLite test and middleware disabled; the database had no users:

```json
{"status":"success","message":"Dashboard metrics retrieved","data":{"users":{"total":0,"active":0,"today":0,"this_week":0},"system":{"php_version":"8.4.25","laravel_version":"13.25.0","environment":"testing"}}}
```

| 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. |
| `data.system.php_version`, `laravel_version`, `environment` | string | Runtime versions and application environment; not BRD indicators. |

| 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 bypassed in local/testing. Error formatting beyond the standard active-account envelope is not verified here.

## 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 };
  system: { php_version: string; laravel_version: string; environment: string };
}
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 and system fields; isolated middleware-disabled test captured 200. |
| 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. | Only endpoint-level RBAC; one shared 60-second cache; module links are not returned. |
| Verification | Auth, RBAC and live production data not verified by capture. | Test bypassed middleware and used isolated SQLite; values above are test data. |

## Version history

| Version | Date | Type | Summary | Dashboard action required |
|---|---|---|---|---|
| 0.1.0 | 2026-11-12 | Initial | Document base metrics and BRD gaps. | Integrate available fields only. |

## Changelog

### 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.