analysis/04-functional-spec/dashboard-module.md
Dashboard
Dashboard Module – Functional Specification
1. Purpose
The Dashboard Module provides the primary landing screen for:
- Admin Panel (Admin Dashboard)
- Provider Portal (Provider Dashboard)
This module displays:
- Key Performance Indicators (KPIs)
- Recent activity summaries
- Quick navigation to important modules
- Performance charts and statistics
2. Involved Entities
| Entity | Description |
|---|---|
| Trip | Counts displayed (active, total) |
| Booking | Counts and recent list |
| User | New user registrations count (Admin only) |
| Provider | Active providers count (Admin only) |
| PaymentTransaction | Revenue summaries |
| AdCampaign | Active campaigns count |
4. Dashboard Components
4.1 Admin Dashboard KPIs
Total Bookings
Total Bookings
New Users
New Users
Total Revenue
Total Revenue
Active Trips
Active Trips
| KPI Card | Arabic Label | Data Source | Description |
|---|---|---|---|
| Total Bookings | إجمالي الحجوزات | bookings.count() | All-time booking count |
| New Users | مستخدمون جدد | users.where(created_at > 30_days) | New registrations in last 30 days |
| Total Revenue | إجمالي الأرباح | SUM(payment_transactions.amount) | Platform earnings |
| Active Trips | الرحلات النشطة | trips.where(status = ACTIVE) | Currently bookable trips |
4.2 Admin Dashboard Charts
| Chart | Arabic Label | Type | Description |
|---|---|---|---|
| Sales Performance | أداء المبيعات | Line/Bar Chart | Revenue over time (daily/weekly/monthly) |
4.3 Admin Dashboard Tables
| Table | Arabic Label | Columns | Description |
|---|---|---|---|
| Recent Bookings | آخر الحجوزات الواردة | Booking #, Customer, Trip, Date, Status | Last 5-10 bookings |
4.4 Provider Dashboard KPIs
| KPI Card | Arabic Label | Data Source | Description |
|---|---|---|---|
| My Trips | رحلاتي | trips.where(provider_id = current) | Provider's total trips |
| My Bookings | حجوزاتي | bookings.where(trip.provider_id = current) | Bookings on provider's trips |
| My Earnings | أرباحي | SUM(financial_records.net_amount) | Provider's net revenue |
| Active Campaigns | الحملات النشطة | ad_campaigns.where(status = ACTIVE) | Provider's active ads |
5. Business Rules
BR-1. Dashboard data is scoped by role
| Role | Data Scope |
|---|---|
| SUPER_ADMIN | All platform data |
| ADMIN | All platform data |
| PROVIDER_ADMIN | Only own provider's data |
| PROVIDER_STAFF | Only own provider's data |
BR-2. KPIs refresh on page load
Data is fetched fresh on each dashboard access. Real-time updates are NOT required for MVP.
BR-3. Chart time ranges
Default time range: Last 30 days. User may toggle between:
- Last 7 days
- Last 30 days
- Last 12 months
BR-4. Recent bookings table
Shows maximum 10 most recent bookings. Clicking a row navigates to booking details.
BR-5. Dashboard is read-only
No CRUD operations on dashboard. All actions require navigation to respective modules.
6. UI Structure
┌─────────────────────────────────────────────────────────┐ │ Sidebar │ Dashboard Content │ │ │ ┌─────────┬─────────┬─────────┬─────────┐ │ │ │ │ KPI │ KPI │ KPI │ KPI │ │ │ │ └─────────┴─────────┴─────────┴─────────┘ │ │ │ ┌─────────────────────────────────────────┐│ │ │ │ Sales Chart ││ │ │ └─────────────────────────────────────────┘│ │ │ ┌─────────────────────────────────────────┐│ │ │ │ Recent Bookings Table ││ │ │ └─────────────────────────────────────────┘│ └─────────────────────────────────────────────────────────┘
7. Status Badges (in Tables)
مؤكدةقيد التنفيذملغاهمكتملةقادمة
| Arabic Label | Color | Enum |
|---|---|---|
| مؤكدة (Confirmed) | Green | CONFIRMED |
| قيد التنفيذ (Pending) | Orange | PENDING |
| ملغاه (Cancelled) | Red/Pink | CANCELLED |
| مكتملة (Completed) | Grey | COMPLETED |
| قادمة (Upcoming) | Blue/Teal | UPCOMING |
8. Error Cases
EC-1. No data available
No data to display
EC-2. Provider account inactive
Company account is not active
EC-3. Loading state
Show skeleton loaders while data fetches.
EC-4. API error
An error occurred while loading data. Please try again.
10. Access Permissions (RBAC)
| Role | Access |
|---|---|
| SUPER_ADMIN | Full admin dashboard |
| ADMIN | Full admin dashboard |
| PROVIDER_ADMIN | Provider dashboard (own data) |
| PROVIDER_STAFF | Provider dashboard (own data, view-only) |
| CUSTOMER | No access |
| FINANCE_ADMIN | Admin dashboard (financial focus) |