libra/docs/stories/story-6.1-dashboard-overview-statistics.md

Story 6.1: Dashboard Overview & Statistics

Epic Reference

Epic 6: Admin Dashboard

User Story

As an admin, I want to see real-time metrics and key statistics at a glance, So that I can understand the current state of my practice.

Prerequisites / Dependencies

This story requires the following to be completed first:

Dependency	Required From	What's Needed
User Model	Epic 2	status (active/deactivated), user_type (individual/company) fields
Consultation Model	Epic 3	consultations table with status, consultation_type, scheduled_date
Timeline Model	Epic 4	timelines table with status (active/archived)
Timeline Updates	Epic 4	timeline_updates table with created_at
Post Model	Epic 5	posts table with status (published/draft), created_at
Admin Layout	Epic 1	Admin authenticated layout with navigation

References:

• Epic 6 details: docs/epics/epic-6-admin-dashboard.md
• PRD Dashboard Section: docs/prd.md Section 5.7 (Admin Dashboard)
• Database Schema: docs/prd.md Section 16.1

Acceptance Criteria

User Metrics Card

• Total active clients (individual + company with status = active)
• Individual vs company breakdown (count each type)
• Deactivated clients count
• New clients this month (created_at in current month)

Booking Metrics Card

• Pending requests count (highlighted with warning color)
• Today's consultations (scheduled for today, approved status)
• This week's consultations
• This month's consultations
• Free vs paid breakdown (consultation_type field)
• No-show rate percentage (no-show / total completed * 100)

Timeline Metrics Card

• Active case timelines (status = active)
• Archived timelines (status = archived)
• Updates added this week (timeline_updates created in last 7 days)

Posts Metrics Card

• Total published posts (status = published)
• Posts published this month

Design

• Clean card-based layout using Flux UI components
• Color-coded status indicators (gold for highlights, success green, warning colors)
• Responsive grid (2 columns on tablet, 1 on mobile, 4 on desktop)
• Navy blue and gold color scheme per PRD Section 7.1

Technical Implementation

Files to Create/Modify

File	Purpose
resources/views/livewire/admin/dashboard.blade.php	Main Volt component
routes/web.php	Add admin dashboard route

Route Definition

Route::middleware(['auth', 'admin'])->prefix('admin')->group(function () {
    Route::get('/dashboard', function () {
        return view('livewire.admin.dashboard');
    })->name('admin.dashboard');
});

Component Structure (Volt Class-Based)

<?php

use App\Models\User;
use App\Models\Consultation;
use App\Models\Timeline;
use App\Models\TimelineUpdate;
use App\Models\Post;
use Illuminate\Support\Facades\Cache;
use Livewire\Volt\Component;

new class extends Component {
    public function with(): array
    {
        return [
            'userMetrics' => $this->getUserMetrics(),
            'bookingMetrics' => $this->getBookingMetrics(),
            'timelineMetrics' => $this->getTimelineMetrics(),
            'postMetrics' => $this->getPostMetrics(),
        ];
    }

    private function getUserMetrics(): array
    {
        return Cache::remember('admin.metrics.users', 300, fn() => [
            'total_active' => User::where('status', 'active')
                ->whereIn('user_type', ['individual', 'company'])->count(),
            'individual' => User::where('user_type', 'individual')
                ->where('status', 'active')->count(),
            'company' => User::where('user_type', 'company')
                ->where('status', 'active')->count(),
            'deactivated' => User::where('status', 'deactivated')->count(),
            'new_this_month' => User::whereMonth('created_at', now()->month)
                ->whereYear('created_at', now()->year)->count(),
        ]);
    }

    private function getBookingMetrics(): array
    {
        return Cache::remember('admin.metrics.bookings', 300, function () {
            $total = Consultation::whereIn('status', ['completed', 'no-show'])->count();
            $noShows = Consultation::where('status', 'no-show')->count();

            return [
                'pending' => Consultation::where('status', 'pending')->count(),
                'today' => Consultation::whereDate('scheduled_date', today())
                    ->where('status', 'approved')->count(),
                'this_week' => Consultation::whereBetween('scheduled_date', [
                    now()->startOfWeek(), now()->endOfWeek()
                ])->count(),
                'this_month' => Consultation::whereMonth('scheduled_date', now()->month)
                    ->whereYear('scheduled_date', now()->year)->count(),
                'free' => Consultation::where('consultation_type', 'free')->count(),
                'paid' => Consultation::where('consultation_type', 'paid')->count(),
                'no_show_rate' => $total > 0 ? round(($noShows / $total) * 100, 1) : 0,
            ];
        });
    }

    private function getTimelineMetrics(): array
    {
        return Cache::remember('admin.metrics.timelines', 300, fn() => [
            'active' => Timeline::where('status', 'active')->count(),
            'archived' => Timeline::where('status', 'archived')->count(),
            'updates_this_week' => TimelineUpdate::where('created_at', '>=', now()->subWeek())->count(),
        ]);
    }

    private function getPostMetrics(): array
    {
        return Cache::remember('admin.metrics.posts', 300, fn() => [
            'total_published' => Post::where('status', 'published')->count(),
            'this_month' => Post::where('status', 'published')
                ->whereMonth('created_at', now()->month)
                ->whereYear('created_at', now()->year)->count(),
        ]);
    }
}; ?>

<div>
    {{-- Dashboard content with Flux UI cards --}}
</div>

Flux UI Components to Use

• <flux:heading> - Page title
• <flux:card> or custom card component - Metric cards (if available, otherwise Tailwind)
• <flux:badge> - Status indicators
• <flux:text> - Metric labels and values

Cache Strategy

• TTL: 300 seconds (5 minutes) for all metrics
• Keys: admin.metrics.users, admin.metrics.bookings, admin.metrics.timelines, admin.metrics.posts
• Invalidation: Consider cache clearing when data changes (optional enhancement)

Edge Cases & Error Handling

Scenario	Expected Behavior
Empty database (0 clients)	All metrics display "0" - no errors
No consultations exist	No-show rate displays "0%" (not "N/A" or error)
New month (1st day)	"This month" metrics show 0
Cache failure	Queries execute directly without caching (graceful degradation)
Division by zero (no-show rate)	Return 0 when total consultations is 0

Testing Requirements

Test File

tests/Feature/Admin/DashboardTest.php

Test Scenarios

// 1. Dashboard loads successfully for admin
test('admin can view dashboard', function () {
    $admin = User::factory()->admin()->create();

    $this->actingAs($admin)
        ->get(route('admin.dashboard'))
        ->assertSuccessful()
        ->assertSee('Dashboard');
});

// 2. Metrics display correctly with sample data
test('dashboard displays correct user metrics', function () {
    User::factory()->count(5)->create(['status' => 'active', 'user_type' => 'individual']);
    User::factory()->count(3)->create(['status' => 'active', 'user_type' => 'company']);
    User::factory()->count(2)->create(['status' => 'deactivated']);

    // Assert metrics show 8 active, 5 individual, 3 company, 2 deactivated
});

// 3. Empty state handling
test('dashboard handles empty database gracefully', function () {
    $admin = User::factory()->admin()->create();

    $this->actingAs($admin)
        ->get(route('admin.dashboard'))
        ->assertSuccessful()
        ->assertSee('0'); // Should show zeros, not errors
});

// 4. No-show rate calculation
test('no-show rate calculates correctly', function () {
    // Create 10 completed, 2 no-shows = 20% rate
});

// 5. Cache behavior
test('metrics are cached for 5 minutes', function () {
    // Verify cache key exists after first load
});

// 6. Non-admin cannot access
test('non-admin cannot access dashboard', function () {
    $client = User::factory()->client()->create();

    $this->actingAs($client)
        ->get(route('admin.dashboard'))
        ->assertForbidden();
});

Manual Testing Checklist

• Verify responsive layout on mobile (375px)
• Verify responsive layout on tablet (768px)
• Verify responsive layout on desktop (1200px+)
• Verify pending count is highlighted/prominent
• Verify color scheme matches PRD (navy blue, gold)
• Verify RTL layout works correctly (Arabic)

Definition of Done

• All metric cards display correctly with accurate data
• Data is cached with 5-minute TTL
• Empty states handled gracefully (show 0, no errors)
• No-show rate handles division by zero
• Responsive layout works on mobile, tablet, desktop
• Color scheme matches brand guidelines
• All tests pass
• Admin-only access enforced
• Code formatted with Pint

Estimation

Complexity: Medium | Effort: 4-5 hours

Out of Scope

• Real-time updates (polling/websockets) - covered in Story 6.3
• Charts and visualizations - covered in Story 6.2
• Quick action buttons - covered in Story 6.3

---

Dev Agent Record

Status

Ready for Review

Agent Model Used

Claude Opus 4.5

File List

File	Action
routes/web.php	Modified - Updated admin dashboard route to use Volt
resources/views/livewire/admin/dashboard.blade.php	Created - Main Volt dashboard component
resources/views/livewire/admin/dashboard-placeholder.blade.php	Deleted - Removed old placeholder
lang/en/admin_metrics.php	Created - English translations for dashboard
lang/ar/admin_metrics.php	Created - Arabic translations for dashboard
tests/Feature/Admin/DashboardTest.php	Created - 21 tests covering all functionality

Completion Notes

• Implemented all 4 metric cards (Users, Bookings, Timelines, Posts)
• Used enums for status comparisons (UserStatus, ConsultationStatus, etc.)
• Implemented 5-minute cache TTL for all metrics
• Added responsive grid layout (1 col mobile, 2 tablet, 4 desktop)
• Used navy blue (#0A1F44) and gold (#D4AF37) color scheme
• Pending requests highlighted with amber badge
• Named translation file admin_metrics.php to avoid collision with __('Dashboard') in sidebar
• All 21 tests pass including edge cases (empty database, division by zero)

Change Log

Date	Change
2025-12-27	Initial implementation of Story 6.1

QA Results

Review Date: 2025-12-27

Reviewed By: Quinn (Test Architect)

Code Quality Assessment

Overall: Excellent - The implementation is clean, well-structured, and follows Laravel/Livewire best practices. The code correctly uses:

• Enums for status comparisons (UserStatus, ConsultationStatus, etc.)
• Eloquent query() method for building queries
• Cache::remember for 5-minute TTL as specified
• Proper separation of concerns with private methods for each metric group
• Bilingual translations (Arabic/English)
• Flux UI components appropriately
• Responsive grid layout per specifications

Refactoring Performed

• File: resources/views/livewire/admin/dashboard.blade.php
  • Change: Fixed braces_position coding standard violation (line 17)
  • Why: Pint linter reported braces_position style issue
  • How: Changed new class extends Component { to new class extends Component with brace on next line

Compliance Check

• Coding Standards: ✓ Passes Pint after fix
• Project Structure: ✓ Follows existing admin component patterns
• Testing Strategy: ✓ 21 Pest tests covering all functionality
• All ACs Met: ✓ All acceptance criteria fully implemented

Improvements Checklist

• Fixed Pint formatting issue (braces_position)
• Consider adding @php /** @var array $userMetrics */ @endphp for IDE type hints (optional enhancement)
• Consider extracting card component for reusability across future dashboard stories (future enhancement)

Security Review

No security concerns identified. The implementation:

• Uses admin middleware for access control
• Does not expose sensitive data
• Uses safe Eloquent queries (no raw SQL)
• Properly scopes metrics to exclude admin users from client counts

Performance Considerations

Well-optimized:

• Cache TTL of 300 seconds (5 minutes) reduces database load
• Uses efficient count() queries instead of loading models
• No N+1 query issues (no relationships loaded)

Minor observation: There are 13 separate count queries when cache is cold. For high-traffic scenarios, these could be consolidated using raw queries, but for an admin dashboard this is perfectly acceptable.

Files Modified During Review

File	Change
resources/views/livewire/admin/dashboard.blade.php	Fixed braces_position Pint style

Gate Status

Gate: PASS → docs/qa/gates/6.1-dashboard-overview-statistics.yml

Recommended Status

✓ Ready for Done - All acceptance criteria met, tests passing, code quality excellent.