alumni_lookup

Engagement Stats System

The Engagement Stats system provides comprehensive analytics and reporting on alumni engagement activities across multiple dimensions and time periods. It’s accessible at /engagement_stats and consists of multiple tabs with different views and calculations.

Overview

The engagement stats system analyzes engagement activities using a sophisticated scoring system that combines:

Core Components

1. Scoring System

Level-Based Points

Based on EngagementType::LEVEL_POINTS:

Activity Caps (Anti-Gaming Protection)

To prevent manipulation through repetitive low-level activities:

Combined Score (Distance Formula)

Rankings use a “distance” calculation balancing quality and breadth:

Distance = √((score × 1.5)² + (capped_activity_count × 1.0)²)

2. Time Period Filtering

Fiscal Year Support

Time Period Options

3. Performance Optimization

Caching Strategy

Database Optimization

Tab Breakdown

Overview Tab

Purpose: High-level engagement statistics and trends

Key Metrics:

Calculations:

Analytics Tab

Purpose: Detailed charts and advanced metrics

Features:

Performance: Intensive mode with detailed processing

Breakdown Tab

Purpose: Activity breakdown by champion role and level

Display:

Data Structure:

@activity_data = {
  "Champion Role Name" => {
    types: [
      {
        name: "Activity Name",
        code: "activity_code",
        level: 2,
        unique_buids: 150,
        descriptions: [
          { description: "Specific activity", count: 50, unique_buids: 45 }
        ]
      }
    ]
  }
}

Demographics Tab

Purpose: Engagement analysis by demographic segments

Segments:

Matrix Tab

Purpose: Quadrant analysis based on score vs. activity count

Quadrants:

Visualization: Scatter plot with quadrant boundaries

Top Alumni Tab

Purpose: Ranked list of most engaged alumni

Ranking: Based on distance formula combining score and activity count Features: Detailed activity breakdowns per alumnus

Activity Pairs Tab

Purpose: Analysis of alumni with specific activity combinations

Use Case: Understanding which activities occur together Export: CSV export functionality available

Technical Implementation

Service Architecture (CRITICAL)

⚠️ All statistics logic MUST be in services, NOT duplicated in the controller.

The EngagementStats:: namespace provides services for each tab. The controller should only:

  1. Instantiate the service with filter parameters
  2. Call the service
  3. Set instance variables from the result
# ✅ Correct pattern - controller delegates to service
def load_demographics_data
  service = EngagementStats::DemographicsService.new(
    start_date: @start_date,
    end_date: @end_date,
    college: @college,
    year: @year
  )
  service.call.each { |key, value| instance_variable_set("@#{key}", value) }
  @last_updated = Rails.cache.read("engagement_stats_last_updated") || Time.current
end
Service Purpose Cache Duration
OverviewService Goal metrics, engagement counts 4 hours
AnalyticsService Charts, score distributions 4 hours
BreakdownService Activity breakdown by role/level 1 hour
DemographicsService Year/college/major breakdowns 1 hour
MatrixService Quadrant analysis scatter plot 1 hour
ActivityPairsService Activity combination analysis 1 hour

Key Design Decisions:

  1. Alumni Counting (not Degrees): All services count unique alumni by BUID, not degree records. An alum with multiple degrees appears once per graduation year.

  2. Built-in Caching: Services use BaseService#with_caching - no need for separate fast/comprehensive modes.

  3. Tested Logic: Services have tests in test/services/engagement_stats/. Controller duplicates are NOT tested.

  4. Degree Classification:

    • Bachelor’s includes Associate’s (A% + B% codes)
    • Doctorate includes D%, J%, P% codes

Controller Structure

EngagementStatsController handles all tab logic with methods:

Key Services

Database Dependencies

Filters and Parameters

URL Parameters

Alumni Filtering

Integration with AlumniFilterService supports:

Performance Considerations

Large Dataset Handling

Caching Strategy

Cache Update Interface

SQL Optimization

UI Features

Visual Elements

Export Capabilities

User Interface Controls

Troubleshooting

Common Issues

  1. Missing Icons: Check SVG files in /public/ directory
  2. Slow Performance: Check for missing database indexes
  3. Cache Issues: Use “Update Now” link or clear Rails cache in production
  4. Data Inconsistencies: Verify engagement_types.champion_role values
  5. Stale Data: Click “Update Now” to force cache refresh after importing new engagement data

Performance Debugging