Admin Dashboard Guide

Last Updated: 2026-01-19 Status: Implemented Plan Reference: 012-admin-dashboard.md, 075-admin-dashboard-improvement.md, 123-universal-dashboard-builder.md, 124-dashboard-builder-improvements.md, 136-widget-service-refactoring.md, 137-dashboard-widget-expansion.md, 138-dashboard-widget-expansion-phase-2.md

Overview

The Admin Dashboard system provides administrators with comprehensive dashboards for monitoring the client portal. The system includes:

1. Static Dashboard - The original dashboard with fixed widgets (/admin/dashboard?static)
2. Universal Dashboard Builder - Create unlimited custom dashboards with 149+ widgets across 10 categories

Table of Contents

1. Accessing Dashboards
2. Dashboard Builder
3. Widget Library
4. Widget Categories
5. Creating Dashboards
6. Managing Widgets
7. Dashboard Templates
8. Technical Architecture
9. Static Dashboard
10. Related Features

Accessing Dashboards

Navigation

Permissions

Only users with the Admin role can access admin dashboards.

Dashboard Builder

Overview

The Universal Dashboard Builder allows admins to:

• Create unlimited named dashboards
• Add widgets from a categorized library (145+ widgets across 10 categories)
• Drag-and-drop to rearrange widgets
• Resize widgets
• Set a default dashboard
• Share dashboards with other admins

Edit Mode

Click Edit Dashboard to enter edit mode:

1. Widget Library - Sidebar appears with available widgets
2. Drag & Drop - Reorder widgets by dragging
3. Resize - Use +/- buttons to adjust widget width
4. Remove - Click X to remove widgets
5. Done Editing - Click to save and exit edit mode

Dashboard Settings

Widget Library

Categories Overview (149+ Total Widgets)

Widget Categories

Communication (8 widgets)

Messages, conversations, and internal notes tracking.

Files & Storage (7 widgets)

File uploads, share links, and storage metrics.

Revenue & Financial (31 widgets)

Core revenue metrics and financial analysis.

Clients (31 widgets)

Client management and stage tracking.

Projects (21 widgets)

Project status and milestone tracking.

Activity (18 widgets)

Activity feed, meetings, and documents.

Compliance & Security (16 widgets)

Compliance scores, security alerts, and workflows.

Time & Resources (11 widgets)

Time tracking and team utilization.

Navigation & Links (2 widgets)

Quick navigation and shortcuts.

System Health (15 widgets)

System health, API monitoring, and quick actions.

Widget Types

Creating Dashboards

From Scratch

1. Navigate to Dashboard > My Dashboards
2. Click Create Dashboard
3. Enter a name and optional description
4. Click Create
5. Enter Edit Mode to add widgets

From Template

1. Navigate to Dashboard > My Dashboards
2. Click From Template
3. Select a template:
   • Admin Overview - Clients, projects, revenue, activity
   • Client Focused - Pipeline, stages, client metrics
   • Compliance - Security checks, audit logs, MFA
   • Analytics Overview - Financial trends, insights

Managing Widgets

Adding Widgets

1. Enter Edit Mode
2. Browse widget library (left sidebar)
3. Click a widget to add it

Removing Widgets

1. Enter Edit Mode
2. Hover over widget
3. Click the red X button

Resizing Widgets

1. Enter Edit Mode
2. Hover over widget
3. Use +/- buttons to adjust width (3-12 columns)

Reordering Widgets

1. Enter Edit Mode
2. Drag widgets to new position
3. Drop to reorder

Dashboard Templates

Admin Overview

Default dashboard for administrators:

• total_clients, active_projects, outstanding_invoices_count, total_revenue
• invoice_status_chart, project_status_chart, revenue_trend_chart
• activity_summary, upcoming_deadlines, quick_actions

Client Focused

Pipeline and client management:

• client_stage_pipeline (full width)
• client_stage_summary, total_clients, new_clients_this_month
• recent_clients, top_clients, at_risk_clients

Compliance Dashboard

Security and compliance monitoring:

• compliance_score, framework_status
• mfa_adoption, inactive_accounts, audit_logs_today, security_alerts
• compliance_checks, open_findings

Analytics Overview

Financial analysis:

• personalized_insights (full width)
• total_invoiced, total_paid, total_overdue, collection_rate
• revenue_trend_chart, invoice_aging_chart
• top_clients

Technical Architecture

Services (Federated Provider Pattern)

The widget system uses a federated provider architecture where each category has its own registry and data provider.

app/Services/Dashboard/
├── Contracts/
│   ├── WidgetDataProviderInterface.php
│   └── WidgetRegistryProviderInterface.php
├── AbstractWidgetDataProvider.php
├── WidgetRegistry.php              # Orchestrator
├── WidgetDataService.php           # Orchestrator
└── Widgets/
    ├── Activity/
    │   ├── ActivityWidgetDataProvider.php
    │   └── ActivityWidgetRegistry.php
    ├── Client/
    │   ├── ClientWidgetDataProvider.php
    │   └── ClientWidgetRegistry.php
    ├── Communication/
    │   ├── CommunicationWidgetDataProvider.php
    │   └── CommunicationWidgetRegistry.php
    ├── Compliance/
    │   ├── ComplianceWidgetDataProvider.php
    │   └── ComplianceWidgetRegistry.php
    ├── Files/
    │   ├── FilesWidgetDataProvider.php
    │   └── FilesWidgetRegistry.php
    ├── Project/
    │   ├── ProjectWidgetDataProvider.php
    │   └── ProjectWidgetRegistry.php
    ├── Revenue/
    │   ├── RevenueWidgetDataProvider.php
    │   └── RevenueWidgetRegistry.php
    ├── SystemHealth/
    │   ├── SystemHealthWidgetDataProvider.php
    │   └── SystemHealthWidgetRegistry.php
    └── TimeResources/
        ├── TimeResourcesWidgetDataProvider.php
        └── TimeResourcesWidgetRegistry.php

Controllers

Models

API Routes

Key Files

app/
├── Http/Controllers/Admin/
│   ├── DashboardController.php
│   └── DashboardBuilderController.php
├── Models/
│   ├── Dashboard.php
│   └── DashboardWidget.php
├── Services/Dashboard/
│   ├── Contracts/
│   ├── AbstractWidgetDataProvider.php
│   ├── WidgetRegistry.php
│   ├── WidgetDataService.php
│   └── Widgets/
│       ├── Activity/
│       ├── Client/
│       ├── Communication/
│       ├── Compliance/
│       ├── Files/
│       ├── Project/
│       ├── Revenue/
│       ├── SystemHealth/
│       └── TimeResources/

resources/views/
├── admin/dashboards/
│   ├── index.blade.php      # Dashboard manager
│   ├── show.blade.php       # Dashboard view with edit mode
│   └── create.blade.php     # Create form
├── components/dashboard/
│   ├── widget-library.blade.php
│   └── widgets/
│       ├── metric.blade.php
│       ├── chart.blade.php
│       ├── list.blade.php
│       ├── list-progress.blade.php
│       ├── table.blade.php
│       ├── pipeline.blade.php
│       ├── pipeline-grouped.blade.php
│       ├── pipeline-rows.blade.php
│       ├── pipeline-list.blade.php
│       ├── pipeline-cards.blade.php
│       ├── metric-grid.blade.php
│       ├── link-grid.blade.php
│       ├── insights.blade.php
│       ├── actions.blade.php
│       ├── summary.blade.php
│       ├── financial-summary.blade.php
│       ├── aging.blade.php
│       └── forecast.blade.php

Adding New Widgets

To add a new widget:

1. Add to Registry: In the appropriate *WidgetRegistry.php, add the widget definition:

   'my_new_widget' => [
       'key' => 'my_new_widget',
       'name' => 'My New Widget',
       'description' => 'Description here',
       'category' => 'clients',
       'type' => 'metric',
       'icon' => 'chart-bar',
       'default_size' => ['w' => 3, 'h' => 1],
       'data_provider' => 'getMyNewWidget',
       'click_url' => 'admin.clients.index',
   ],
   

2. Add Data Provider Method: In the corresponding *WidgetDataProvider.php:

   public function getMyNewWidget(): array
   {
       return [
           'value' => 42,
           'label' => 'My Metric',
       ];
   }
   

3. Register in getSupportedWidgets(): Add the widget key to the provider's supported list.

Technical Notes

Tailwind Dynamic Classes

Widget column spans use dynamic class names (col-span-{width}). These are safelisted in tailwind.config.js to prevent purging:

• col-span-1 through col-span-12
• md:col-span-1 through md:col-span-12
• lg:col-span-1 through lg:col-span-12

Drag and Drop

The drag-and-drop system uses HTML5 native drag events with a placeholder-based approach:

• Dragged widget is marked with isDragging: true and styled as semi-transparent
• A dashed placeholder appears at the drop position
• Position is calculated based on mouse position relative to widget centers
• Charts are reinitialized after drop via $nextTick(() => this.initCharts())

Chart Reinitialization

Charts must be reinitialized after certain operations:

• After drag-and-drop (finalizeDrop())
• After widget resize (resizeWidget())
• After widget deletion (removeWidget())
• This is handled via this.$nextTick(() => this.initCharts())

Widget Key Format

Widget keys in the JavaScript widgets object use string prefixes (e.g., widget_102) to preserve PHP's insertion order, since Object.entries() sorts numeric keys.

Static Dashboard

The original static dashboard remains available at /admin/dashboard?static:

Overview Cards

Charts

• Invoice Status (doughnut)
• Project Status (doughnut)
• Revenue Trend (line)

Activity

• Activity summary by period
• Recent activity feed

Lists

• Overdue invoices
• Upcoming project deadlines

Related Features

Best Practices

For Dashboard Design

1. Start with templates - Use pre-built templates as starting points
2. Group related widgets - Keep metrics together by category
3. Use full-width wisely - Pipeline and insights work well full-width
4. Limit widgets - 8-12 widgets per dashboard for clarity

For Performance

1. Refresh sparingly - Data is cached for performance
2. Use specific dashboards - Different dashboards for different tasks
3. Remove unused widgets - Keep dashboards focused

Troubleshooting

See Also

• Client Dashboard - Client portal view
• Analytics - Business intelligence
• Audit & Compliance - Security monitoring
• Time Tracking - Time entry system