Analytics & Business Intelligence Guide

Last Updated: 2026-01-10 Status: Implemented Plan References:

• 037-analytics-business-intelligence.md
• 052-analytics-enhancement.md

Overview

The Analytics & Business Intelligence system provides data-driven insights into portal usage, business performance, and trends. It includes interactive dashboards, KPI tracking, trend analysis, predictive insights, drill-down exploration, period comparisons, and comprehensive export capabilities to help administrators make informed decisions.

Table of Contents

1. Accessing Analytics
2. Dashboard Overview
3. Key Metrics
4. Charts & Visualizations
5. Period Comparisons
6. Trend Analysis
7. Drill-Down Exploration
8. Export Options
9. Custom Dashboards
10. Technical Architecture
11. Related Features

Accessing Analytics

Navigation

Permissions

Dashboard Overview

Main Dashboard

The analytics dashboard provides at-a-glance insights:

Time Period Selection

Key Metrics

Revenue Metrics

Client Metrics

Project Metrics

Engagement Metrics

Charts & Visualizations

Chart Types

The system supports 18 chart types via the ChartBuilder service:

Advanced Chart Types (Plan 052)

Sankey Chart

• Visualizes flow of values between categories
• Shows source → target relationships with proportional widths
• Use for: Revenue flows, customer journey, resource allocation

Funnel Chart

• Shows conversion through stages
• Each stage shows value and percentage of previous
• Use for: Sales pipeline, lead conversion, process completion

Waterfall Chart

• Displays incremental changes to a starting value
• Shows positive (green) and negative (red) changes
• Supports subtotals at specific indices
• Use for: Cash flow, budget variance, cumulative impact

Bubble Chart

• 3-dimensional scatter plot (x, y, radius)
• Can group by category with different colors
• Use for: Client analysis, portfolio visualization

Sparkline Chart

• Compact inline chart for dashboards
• Shows trend direction and change percentage
• Minimal chrome, maximum data density
• Use for: KPI cards, tables with trends

Period Comparisons

Overview

Compare metrics across multiple time periods to identify trends and performance changes.

Location: /admin/analytics/comparisons

Comparison Types

Available Metrics

Comparison Output

Each comparison returns:

[
    'metric' => 'revenue',
    'metric_label' => 'Revenue',
    'comparison_type' => 'year_over_year',
    'periods' => [
        [
            'label' => '2023',
            'start' => '2023-01-01',
            'end' => '2023-12-31',
            'value' => 150000,
            'change' => null,
            'change_percent' => null,
            'trend' => 'neutral',
        ],
        [
            'label' => '2024',
            'start' => '2024-01-01',
            'end' => '2024-12-31',
            'value' => 185000,
            'change' => 35000,
            'change_percent' => 23.33,
            'trend' => 'up',
        ],
    ],
    'summary' => [
        'overall_change' => 35000,
        'overall_change_percent' => 23.33,
        'overall_trend' => 'up',
        'best_period' => '2024',
        'worst_period' => '2023',
        'average' => 167500,
        'max' => 185000,
        'min' => 150000,
    ],
];

Saving Comparisons

Save frequently-used comparisons for quick access:

1. Configure comparison parameters
2. Click "Save Comparison"
3. Name the comparison
4. Optionally pin to dashboard
5. Access from saved comparisons list

Trend Analysis

Overview

Analyze data trends using statistical methods for insights and forecasting.

Location: /admin/analytics/trends

Analysis Components

Trend Calculation

// Example trend result
[
    'direction' => 'up',        // up, down, stable, insufficient_data
    'slope' => 2.5,             // Rate of change per period
    'r_squared' => 0.95,        // Correlation coefficient
    'intercept' => 100,         // Y-intercept
    'strength' => 'strong',     // Trend strength
]

Moving Averages

Forecasting

Uses linear regression with confidence intervals:

[
    'periods' => [
        [
            'period' => '2024-07',
            'value' => 182500,
            'confidence_lower' => 165000,
            'confidence_upper' => 200000,
        ],
        // ... more forecast periods
    ],
    'method' => 'linear_regression',
    'confidence_level' => 0.95,
]

Anomaly Detection

Identifies unusual values using Z-score analysis:

[
    [
        'period' => '2024-04',
        'value' => 500000,
        'expected' => 150000,
        'z_score' => 4.5,
        'type' => 'high',       // high or low
    ],
]

Growth Analysis

[
    'total_growth_percent' => 33.1,
    'average_period_growth' => 10.0,
    'cagr' => 8.5,              // Compound annual growth rate
    'growth_consistency' => 0.85,
]

Drill-Down Exploration

Overview

Explore data hierarchically, drilling from summary to detail levels.

Location: /admin/analytics/drill-down

Available Hierarchies

Using Drill-Down

1. Select Hierarchy: Choose the dimension to explore
2. View Summary: See top-level aggregation
3. Click to Drill: Select a value to drill deeper
4. View Breadcrumb: Track your drill path
5. Navigate: Use breadcrumb to jump to any level
6. Save Path: Bookmark useful drill paths

Drill-Down Response

[
    'hierarchy' => 'revenue',
    'hierarchy_name' => 'Revenue',
    'metric' => 'revenue',
    'current_level' => 1,
    'current_level_name' => 'year',
    'next_level' => 'quarter',
    'can_drill_deeper' => true,
    'path' => ['2024'],
    'breadcrumb' => [
        ['level' => 'year', 'value' => '2024'],
    ],
    'data' => [
        ['dimension' => '1', 'label' => 'Q1 2024', 'value' => 45000, 'drillable' => true],
        ['dimension' => '2', 'label' => 'Q2 2024', 'value' => 52000, 'drillable' => true],
        ['dimension' => '3', 'label' => 'Q3 2024', 'value' => 48000, 'drillable' => true],
        ['dimension' => '4', 'label' => 'Q4 2024', 'value' => 55000, 'drillable' => true],
    ],
    'total' => 200000,
]

Saved Drill Paths

Save and bookmark frequently-used drill paths:

Export Options

Overview

Export analytics data in multiple formats for reporting and external analysis.

Location: /admin/analytics/exports

Supported Formats

Export Types

Creating an Export

1. Navigate to analytics section
2. Click "Export" button
3. Select format
4. Configure options:
   • Include charts
   • Include data tables
   • Date range
   • Filters
5. Click "Generate Export"
6. Download when ready (background processing for large exports)

Export Status

Automatic Cleanup

Exports are automatically cleaned up after configured retention period (default: 7 days).

Custom Dashboards

Creating a Dashboard

1. Navigate to Admin → Analytics → Dashboards
2. Click "Create Dashboard"
3. Enter dashboard name
4. Add widgets:
   • Click "Add Widget"
   • Select widget type (Chart, KPI, Table)
   • Configure data source
   • Set dimensions and metrics
5. Arrange widgets by dragging
6. Click "Save Dashboard"

Widget Types

Sharing Dashboards

1. Open dashboard
2. Click "Share"
3. Options:
   • Copy link (view-only)
   • Schedule email delivery
   • Export as PDF/PPTX

Technical Architecture

Models

SavedComparison Model: app/Models/SavedComparison.php

class SavedComparison extends Model
{
    protected $fillable = [
        'name',
        'description',
        'metric',
        'comparison_type',
        'periods',
        'filters',
        'visualization',
        'is_pinned',
        'created_by',
    ];

    protected $casts = [
        'periods' => 'array',
        'filters' => 'array',
        'visualization' => 'array',
        'is_pinned' => 'boolean',
    ];

    const METRICS = [
        'revenue' => 'Revenue',
        'invoices' => 'Invoice Count',
        'projects' => 'Project Count',
        'clients' => 'Client Count',
        'collection_rate' => 'Collection Rate',
        'project_completion' => 'Project Completion Rate',
        'client_retention' => 'Client Retention Rate',
    ];
}

AnalyticsExport Model: app/Models/AnalyticsExport.php

class AnalyticsExport extends Model
{
    protected $fillable = [
        'name',
        'type',
        'format',
        'status',
        'parameters',
        'file_path',
        'file_size',
        'error_message',
        'started_at',
        'completed_at',
        'expires_at',
        'created_by',
    ];

    protected $casts = [
        'parameters' => 'array',
        'started_at' => 'datetime',
        'completed_at' => 'datetime',
        'expires_at' => 'datetime',
    ];
}

AnalyticsDrillPath Model: app/Models/AnalyticsDrillPath.php

class AnalyticsDrillPath extends Model
{
    protected $fillable = [
        'name',
        'metric',
        'hierarchy',
        'path',
        'filters',
        'is_bookmarked',
        'user_id',
    ];

    protected $casts = [
        'path' => 'array',
        'filters' => 'array',
        'is_bookmarked' => 'boolean',
    ];

    const HIERARCHIES = [
        'revenue' => [
            'name' => 'Revenue',
            'levels' => ['year', 'quarter', 'month', 'week', 'day'],
        ],
        'time' => [
            'name' => 'Time',
            'levels' => ['year', 'quarter', 'month', 'week', 'day', 'hour'],
        ],
        'clients' => [
            'name' => 'Clients',
            'levels' => ['industry', 'size', 'region', 'client'],
        ],
        'projects' => [
            'name' => 'Projects',
            'levels' => ['status', 'type', 'client', 'project'],
        ],
        'geography' => [
            'name' => 'Geography',
            'levels' => ['country', 'state', 'city'],
        ],
    ];
}

Services

ComparisonService: app/Services/Analytics/ComparisonService.php

TrendAnalyzer: app/Services/Analytics/TrendAnalyzer.php

DrillDownService: app/Services/Analytics/DrillDownService.php

AnalyticsExportService: app/Services/Analytics/AnalyticsExportService.php

ChartBuilder: app/Services/Reports/ChartBuilder.php

Controllers

Routes

// Analytics routes (in web.php)
Route::prefix('admin/analytics')->middleware(['auth', 'admin'])->group(function () {
    // Existing routes...

    // Comparisons
    Route::get('comparisons', [ComparisonController::class, 'index']);
    Route::post('comparisons/compare', [ComparisonController::class, 'compare']);
    Route::get('comparisons/year-over-year', [ComparisonController::class, 'yearOverYear']);
    Route::get('comparisons/quarter-over-quarter', [ComparisonController::class, 'quarterOverQuarter']);
    Route::get('comparisons/month-over-month', [ComparisonController::class, 'monthOverMonth']);
    Route::resource('comparisons', ComparisonController::class)->only(['store', 'destroy']);
    Route::post('comparisons/{comparison}/run', [ComparisonController::class, 'run']);
    Route::patch('comparisons/{comparison}/toggle-pin', [ComparisonController::class, 'togglePin']);

    // Exports
    Route::get('exports', [AnalyticsExportController::class, 'index']);
    Route::post('exports', [AnalyticsExportController::class, 'store']);
    Route::get('exports/{export}', [AnalyticsExportController::class, 'show']);
    Route::get('exports/{export}/download', [AnalyticsExportController::class, 'download']);
    Route::delete('exports/{export}', [AnalyticsExportController::class, 'destroy']);
    Route::get('exports/meta/formats', [AnalyticsExportController::class, 'formats']);
    Route::get('exports/meta/types', [AnalyticsExportController::class, 'types']);
    Route::post('exports/cleanup', [AnalyticsExportController::class, 'cleanup']);

    // Drill-down
    Route::get('drill-down', [DrillDownController::class, 'index']);
    Route::get('drill-down/hierarchies', [DrillDownController::class, 'hierarchies']);
    Route::post('drill-down/explore', [DrillDownController::class, 'drillDown']);
    Route::post('drill-down/drill-into', [DrillDownController::class, 'drillInto']);
    Route::post('drill-down/drill-up', [DrillDownController::class, 'drillUp']);
    Route::post('drill-down/jump', [DrillDownController::class, 'jumpToLevel']);
    Route::resource('drill-down/paths', DrillDownController::class)->only(['store', 'destroy']);
    Route::get('drill-down/paths/{path}/load', [DrillDownController::class, 'load']);
    Route::patch('drill-down/paths/{path}/toggle-bookmark', [DrillDownController::class, 'toggleBookmark']);

    // Trends
    Route::post('trends/analyze', [TrendController::class, 'analyze']);
    Route::post('trends/trend', [TrendController::class, 'trend']);
    Route::post('trends/statistics', [TrendController::class, 'statistics']);
    Route::post('trends/moving-averages', [TrendController::class, 'movingAverages']);
    Route::post('trends/forecast', [TrendController::class, 'forecast']);
    Route::post('trends/anomalies', [TrendController::class, 'anomalies']);
    Route::post('trends/seasonality', [TrendController::class, 'seasonality']);
    Route::post('trends/growth', [TrendController::class, 'growth']);
    Route::post('trends/periods', [TrendController::class, 'periods']);
});

Data Caching

Analytics queries are cached for performance:

// Cache revenue metrics for 1 hour
Cache::remember('analytics:revenue:' . $period, 3600, function () use ($start, $end) {
    return $this->analyticsService->getRevenueMetrics($start, $end);
});

Cache Invalidation

Cache is cleared when relevant data changes:

// In Invoice observer
public function updated(Invoice $invoice): void
{
    if ($invoice->wasChanged('status') && $invoice->status === 'paid') {
        Cache::tags(['analytics', 'revenue'])->flush();
    }
}

Related Features

Dependencies

Complementary Features

Best Practices

For Data Accuracy

1. Use consistent date ranges for comparisons
2. Understand metric definitions
3. Verify data sources before decisions
4. Consider seasonality in trends
5. Check anomaly context before acting

For Performance

1. Cache expensive queries appropriately
2. Use date range limits on large datasets
3. Aggregate data for historical views
4. Index analytical columns
5. Use background jobs for exports

For Comparisons

1. Compare like periods (same duration)
2. Account for business changes between periods
3. Use multiple metrics for context
4. Consider external factors in analysis

For Drill-Down

1. Save useful paths for repeated analysis
2. Use breadcrumbs to navigate
3. Apply filters at appropriate levels
4. Export detail data for deep analysis

Troubleshooting

See Also

• Reports - Detailed reporting
• Admin Dashboard - Overview
• Activity Logging - Activity tracking