alumni_lookup

Alumni Lookup — Product Overview

Version: 1.0
Last Updated: November 2025
Audience: Consumers, Product Managers, Engineers, Designers, Investors

Table of Contents

  1. Product Summary
  2. Value Proposition
  3. Core Features
  4. System Architecture Overview
  5. Data Model Overview
  6. User Journeys
  7. Operational Model
  8. Metrics and Success Criteria
  9. Roadmap Snapshot
  10. Risks and Assumptions
  11. Glossary

1. Product Summary

What It Is

Alumni Lookup is a web-based platform that helps universities track, measure, and grow alumni engagement. It serves as the central hub for managing alumni data, monitoring engagement activities, and coordinating the Alumni Champion program at Belmont University.

Who It Serves

The Core Problem It Solves

Universities struggle to understand which alumni are truly engaged versus merely present in their database. Traditional systems track contact information but not relationship depth. Alumni Lookup transforms passive contact records into actionable engagement intelligence—helping staff identify their most engaged supporters, discover untapped potential, and measure the effectiveness of outreach programs.

Plain-Language Summary

Imagine having a database of thousands of alumni and not knowing who actually cares about your institution. Alumni Lookup solves this by scoring every interaction an alumnus has with the university—attending events, clicking emails, making donations, volunteering—and rolling it into a single engagement picture. Staff can instantly see who’s highly engaged, who’s falling off, and who might become a champion for the university with the right outreach. It’s like having a relationship health monitor for your entire alumni network.

2. Value Proposition

For Consumers/Users (Alumni Engagement Staff)

Before After
Searching through spreadsheets to find alumni Instant search with accent-insensitive name matching
Manually tracking engagement in separate systems Automated engagement scoring across all touchpoints
Guessing which alumni to prioritize Data-driven ranking of most engaged alumni
Tedious CSV exports for CRM One-click exports with Salesforce-ready Contact IDs
No visibility into event impact Flagship event tracking with follow-up metrics

Key Benefits:

For Product/Business Owners

Value Area Impact
Engagement Visibility Clear metrics on program effectiveness
Resource Allocation Focus staff time on high-potential alumni
Program Growth Track champion pipeline from prospect to completion
Institutional Memory Centralized engagement history that survives staff turnover
CRM Integration Seamless data flow to Salesforce via Contact ID mapping

Key Benefits:

For Engineers/Technical Stakeholders

Technical Value Details
Modern Stack Ruby on Rails 7.1, PostgreSQL, Tailwind CSS, Hotwire
Clean Architecture Service objects isolate business logic; RESTful controllers
Smart Search PostgreSQL full-text search with unaccent extension
Performance Caching strategies, batch processing, query optimization
Maintainability Comprehensive documentation, established conventions
Extensibility Two-portal architecture ready for Champion Portal expansion

Key Benefits:

For Investors/Executive Stakeholders

Strategic Value Significance
Alumni Engagement Direct driver of donations and institutional support
Operational Efficiency Reduces manual effort in alumni relations
Scalable Platform Architecture supports growth without rebuild
Champion Network Multiplies engagement staff through volunteer ambassadors
Data Asset Engagement intelligence becomes institutional knowledge

Key Benefits:

3. Core Features

3.1 Alumni Search & Management

What It Does:
Provides instant access to alumni records with powerful search capabilities across names, degrees, locations, and engagement status.

User Benefit:
Find any alumnus in seconds—even with misspelled names or missing accent marks—and immediately see their full engagement picture.

Non-Technical View Technical View
Type a name, get results PostgreSQL full-text search with pg_search gem
Works with accents (Shardé = Sharde) unaccent PostgreSQL extension
Filter by college, year, status Composable query scopes with Kaminari pagination
See alumni photo and contact info Active Storage with Cloudinary for image hosting

3.2 Engagement Scoring System

What It Does:
Automatically calculates an engagement score for every alumnus based on their activities, with built-in protections against “gaming” the numbers.

User Benefit:
Know at a glance who your most engaged alumni are—and trust the numbers because they’re weighted fairly.

Non-Technical View Technical View
Activities earn points (1-10 based on importance) Level-based scoring: L1=1pt, L2=3pts, L3=7pts, L4=10pts
High-value actions (donations, volunteering) count more Activity types assigned levels 0-4 in engagement_types table
Can’t game the system with endless email clicks Activity caps: email_click max 5, event_rsvp max 2
Balanced score considers quality AND quantity Distance formula: √((score × 1.5)² + (activity_count × 1.0)²)

3.3 Top Engaged Alumni Rankings

What It Does:
Ranks alumni by their combined engagement score and activity breadth, with time period filtering.

User Benefit:
Quickly identify your top 50 most engaged alumni for the last month, quarter, year, or all time—ready for outreach or recognition.

Non-Technical View Technical View
Filter by 30 days, 6 months, 1 year, all time Date range filtering with fiscal year support
See detailed activity breakdown per person Eager-loaded associations with batch processing
Sorted by balanced engagement “distance” Combined score calculation in TopEngagedAlumniService
Exportable to CSV for outreach campaigns CsvExportService with CRM-ready Contact IDs

3.4 Engagement Stats Dashboard

What It Does:
Multi-tab analytics dashboard showing engagement trends, demographic breakdowns, and activity patterns.

User Benefit:
Get instant visibility into overall engagement health, college-by-college performance, and activity type effectiveness.

Non-Technical View Technical View
Overview with key metrics Cached calculations with 1-4 hour refresh
Analytics with charts Turbo-powered partial page updates
Breakdown by activity type Grouped queries with champion role categorization
Matrix quadrant view Score vs. activity count scatter analysis
Demographics analysis Joins through degree → major → college chain

Dashboard Tabs:

  1. Overview — Summary stats and score distribution
  2. Analytics — Trend charts and advanced metrics
  3. Breakdown — Activities grouped by champion role and level
  4. Demographics — Engagement by graduation year, college, location
  5. Matrix — Quadrant view: Committed, Purposeful, Frequent, Untapped
  6. Top Alumni — Ranked list with expandable details

3.5 Champion & Prospect Management

What It Does:
Tracks the champion pipeline from initial prospect identification through completed signup, with status visibility across the application.

User Benefit:
Never lose track of a potential champion—see exactly where they are in the signup process and manage prospects efficiently.

Non-Technical View Technical View
5-stage champion signup tracking Integer enum: started(1) → zip_code(5)
Manual prospect flagging prospect_status enum on Alumni model
Visual status indicators throughout app Color-coded borders: blue (complete), yellow (in-progress), sky (prospect)
Prospect notes and management Modal-based UI with Turbo frame updates
Filter alumni by champion status 6 filter options in search interface

Champion Signup Stages:

  1. Started — Initial form submitted
  2. Completed Questions — Basic information provided
  3. Selected Role — Champion role chosen
  4. Interests — Interest categories selected
  5. Zip Code — Complete (full champion)

3.6 Data Import/Export System

What It Does:
Bulk import degrees, engagement activities, and alumni lists via CSV with preview validation before commit.

User Benefit:
Upload hundreds of records at once without worry—preview catches errors before they enter the system.

Non-Technical View Technical View
Upload CSV, map columns, preview Three-step workflow: upload → preview → commit
Auto-creates missing alumni records Upsert logic in DegreeImportService
Flexible header matching Case-insensitive, alias-aware column mapping
CRM-ready exports “AdvRM - Contact ID” field for Salesforce (C-000000000 format)
Error reporting before commit Validation summary with row-level feedback

3.7 Flagship Event Tracking

What It Does:
Identifies major institutional events (Homecoming, Campaign Launch, etc.) and tracks which attendees show follow-up engagement.

User Benefit:
Measure event impact beyond attendance—see who actually deepened their engagement afterward.

Non-Technical View Technical View
Auto-detects flagship events by name Keyword matching: homecoming, reunion weekend, etc.
Shows attendance counts activity_code: 'event_attended' filtering
Tracks follow-up engagement Subsequent L2+ activities after event date
Measures event effectiveness Follow-up rate calculations per event

4. System Architecture Overview

Major Components

┌─────────────────────────────────────────────────────────────────────────┐
│                        ALUMNI LOOKUP SYSTEM                             │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                 │
│  │   Browser   │───▶│ Rails App   │───▶│ PostgreSQL  │                 │
│  │  (Turbo)    │◀───│  (Puma)     │◀───│  Database   │                 │
│  └─────────────┘    └─────────────┘    └─────────────┘                 │
│         │                  │                  │                         │
│         │           ┌──────┴──────┐           │                         │
│         │           │             │           │                         │
│         ▼           ▼             ▼           ▼                         │
│  ┌─────────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────┐               │
│  │  Tailwind   │ │Services │ │ Devise  │ │  pg_search  │               │
│  │  Frontend   │ │ Layer   │ │  Auth   │ │ Full-text   │               │
│  └─────────────┘ └─────────┘ └─────────┘ └─────────────┘               │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    EXTERNAL INTEGRATIONS                         │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐                       │   │
│  │  │Cloudinary│  │ Mailgun  │  │Salesforce│                       │   │
│  │  │ (Images) │  │ (Email)  │  │  (CRM)   │                       │   │
│  │  └──────────┘  └──────────┘  └──────────┘                       │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

How Data Flows

  1. User Request → Browser sends request via Turbo (minimal page reloads)
  2. Authentication → Devise validates user session
  3. Controller → Routes request to appropriate controller action
  4. Service Layer → Business logic executed in service objects
  5. Model Layer → ActiveRecord handles database operations
  6. Database → PostgreSQL stores and retrieves data
  7. Response → Turbo streams update only changed page sections

Key Integrations

Integration Purpose Data Flow
Cloudinary Image hosting Alumni photos uploaded and transformed
Mailgun Transactional email Champion signup notifications
Salesforce CRM sync Contact ID mapping for imports/exports
PostgreSQL Extensions Search unaccent for accent-insensitive queries

Architectural Patterns

Pattern Implementation Benefit
Service Objects 9 services in app/services/ Business logic isolated from controllers
RESTful Controllers 18 controllers following REST conventions Predictable URL structure
Hotwire/Turbo Turbo frames and streams Fast, minimal-reload UI
Import Map No JavaScript bundler Simplified frontend tooling
Two-Portal Design Separate internal/external namespaces Ready for Champion Portal expansion

Constraints

5. Data Model Overview

Primary Entities

Entity Purpose Key Fields
Alumni Core person record buid (unique ID), name, contact info, contact_id (Salesforce)
Degree Academic credentials degree_code, degree_date, links to major
EngagementActivity Individual interactions activity_code, engagement_date, description
EngagementType Activity definitions code, level (0-4), champion_role
ChampionSignup Champion pipeline status (1-5), role selection, interests
College/Major Academic structure Reference tables for filtering
User System authentication Devise-managed, admin flag

High-Level Relationships

                         ┌──────────────┐
                         │   College    │
                         └──────┬───────┘
                                │
                         ┌──────▼───────┐
                         │    Major     │
                         └──────┬───────┘
                                │
┌──────────────┐         ┌──────▼───────┐         ┌──────────────────┐
│ChampionSignup│◀────────│   Alumni     │────────▶│ EngagementActivity│
└──────────────┘         │   (buid)     │         └────────┬─────────┘
                         └──────┬───────┘                  │
                                │                   ┌──────▼───────┐
                         ┌──────▼───────┐           │EngagementType│
                         │   Degree     │           └──────────────┘
                         └──────────────┘

What Data Matters Most

Data Type Why It Matters
Engagement Activities The raw material for all scoring and analytics
BUID The universal key linking all alumni data
Contact ID Enables Salesforce/CRM synchronization
Champion Status Tracks volunteer pipeline progression
Degree Info Powers demographic analysis and college breakdowns

Data Origin and Consumption

Data Origin How Consumed
Alumni records Initial database migration, CSV import Search, profile display, exports
Engagement activities CSV import from various systems Scoring, rankings, analytics
Degrees CSV import from registrar Demographic filtering, fiscal year calculations
Champion signups Web form submissions Pipeline tracking, prospect management
Contact IDs Salesforce export, manual entry CRM sync, export matching

6. User Journeys

Journey 1: Staff Member Searches for Alumni (Consumer-Facing)

Scenario: A development officer needs to find alumni in Nashville who graduated in the last 10 years and are highly engaged.

Before Alumni Lookup:

With Alumni Lookup:

┌─────────────────────────────────────────────────────────────────┐
│ STEP 1: Search                                                  │
│ • Navigate to Alumni Search                                     │
│ • Enter filters: City = Nashville, Grad Year = 2015-2025       │
│ • Apply champion status filter: "Highly Engaged"               │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 2: Review Results                                          │
│ • See paginated list with engagement scores                    │
│ • Quick view of contact info and degrees                       │
│ • Engagement level badges visible                              │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 3: Export or Drill Down                                    │
│ • Click alumnus for full profile with activity history         │
│ • Or export filtered list to CSV for outreach                  │
│ • Contact ID included for Salesforce import                    │
└─────────────────────────────────────────────────────────────────┘

After: 2-3 minutes, accurate results, ready for action.

Journey 2: Admin Imports Monthly or Quarterly Engagement Data (Internal Operations)

Scenario: The data coordinator receives monthly or quarterly engagement data from the events team and email platform, needing to add 5,000+ activities.

Before Alumni Lookup:

With Alumni Lookup:

┌─────────────────────────────────────────────────────────────────┐
│ STEP 1: Prepare CSV                                             │
│ • Format: buid, activity_code, description, engagement_date    │
│ • Headers can vary—system maps flexibly                        │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 2: Upload & Preview                                        │
│ • Select file and upload                                       │
│ • Map columns if needed (auto-detected usually)                │
│ • System shows preview: X records ready, Y errors found        │
│ • Review specific error rows before proceeding                 │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 3: Commit Import                                           │
│ • Click "Import" to commit validated records                   │
│ • System processes in batches for performance                  │
│ • Summary shows: 4,850 imported, 150 skipped (with reasons)    │
└─────────────────────────────────────────────────────────────────┘

After: 10-15 minutes, zero data corruption risk, full audit trail.

Scenario: The Alumni Relations Director needs to prepare a board report showing engagement health by college and identify emerging champions.

Before Alumni Lookup:

With Alumni Lookup:

┌─────────────────────────────────────────────────────────────────┐
│ STEP 1: Access Dashboard                                        │
│ • Navigate to Engagement Stats                                 │
│ • Select fiscal year or date range                             │
│ • View Overview tab for summary metrics                        │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 2: Analyze by College                                      │
│ • Switch to Demographics tab                                   │
│ • See engagement breakdown by college                          │
│ • Identify high and low performing segments                    │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 3: Review Matrix & Top Engaged                             │
│ • Matrix tab shows quadrant distribution                       │
│ • Top Alumni tab lists emerging champions                      │
│ • Flag promising alumni as prospects for follow-up             │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────────────┐
│ STEP 4: Export for Board                                        │
│ • Export relevant views to CSV                                 │
│ • Take screenshots of key visualizations                       │
│ • Data ready for board presentation                            │
└─────────────────────────────────────────────────────────────────┘

After: Same day, self-service, always current data.

7. Operational Model

How the Product Is Maintained

Area Approach
Hosting Heroku with PostgreSQL
Deployments Git-based deployment to Heroku
Database Backups Heroku automated daily backups
Image Storage Cloudinary (production), local (development)
Monitoring Heroku metrics, log monitoring
Caching Rails cache with configurable TTLs (1-4 hours)

Teams and Roles

Role Responsibilities
Alumni Engagement Staff Daily search, research, prospect management
Data Coordinator CSV imports, data quality, duplicate management
Director/Manager Analytics review, strategic planning, board reporting
System Admin User management, settings, access control
Developer Feature development, bug fixes, deployments

Key Workflows

Support Workflow

  1. User encounters issue → Reports via email/ticket
  2. Admin reviews → Checks logs and data
  3. Resolution → Fix applied or guidance provided
  4. Documentation → Update troubleshooting guides if recurring

Data Update Workflow

  1. Source system exports data (events, email, giving)
  2. Data coordinator formats CSV
  3. Preview import → Validate and fix errors
  4. Commit import → Activities appear in system
  5. Cache refresh → “Update Now” clears stale analytics

Champion Pipeline Workflow

  1. Alumni starts signup → Status = 1 (Started)
  2. Progresses through stages → Status updates (2→3→4→5)
  3. Completes signup → Becomes full Champion (status = 5)
  4. Manual prospects → Staff flags promising alumni
  5. Outreach → Staff contacts prospects to encourage signup

Input/Output Patterns

Input Output
Alumni CSV Updated alumni records
Engagement CSV New activities, recalculated scores
Degree CSV Academic records, auto-created alumni
Search queries Filtered alumni lists
Date range filters Time-bounded analytics
Prospect flags Champion pipeline tracking
Export requests Salesforce-ready CSV files

8. Metrics and Success Criteria

Product Metrics

Metric Description Target
Active Users Staff logging in weekly 100% of engagement team
Search Volume Alumni searches per week Tracking baseline
Export Frequency CSV exports for campaigns Tracking baseline
Prospect Conversion Prospects becoming champions 20%+ conversion rate
Data Freshness Days since last engagement import < 7 days

Business Metrics

Metric Description Target
Time Savings Hours saved on alumni research 10+ hrs/week per staff
Champion Growth Active champions in network Year-over-year increase
Engagement Rate % of alumni with engagement activity Track and grow
Event ROI Attendees with follow-up engagement 40%+ follow-up rate
Data Quality Records with Contact ID populated 90%+ for active alumni

Technical Metrics

Metric Description Target
Availability Uptime percentage 99.5%+
Response Time Page load time < 2 seconds
Search Performance Search query response < 500ms
Import Throughput Records processed per minute 1000+
Test Coverage Code covered by tests Expanding (241+ tests)
Error Rate Application errors per day < 5

9. Roadmap Snapshot

Immediate Priorities (Next 1-3 Months)

Priority Description Status
Role-Based Access Implement Admin vs. Staff permissions Preparation complete
Test Coverage Expand automated test suite In progress
Performance Tuning Optimize large dataset queries Ongoing
Documentation Complete API and feature docs Ongoing

Mid-Term Enhancements (3-6 Months)

Enhancement Description Estimated Effort
Champion Portal Foundation Auth, profiles, directory for champions 8-12 weeks
Advanced Search Saved searches, complex filters 2-4 weeks
Batch Operations Bulk prospect flagging, mass updates 2-3 weeks
Reporting Improvements Scheduled reports, PDF exports 4-6 weeks

Long-Term Vision (6-12 Months)

Vision Area Description
Champion Portal Full-featured external portal at champions.bualum.co
Community Features Discussion boards, event contributions, mentorship
Regional Coordination CLC (City Leadership Council) admin tools
Self-Service Analytics Custom report builder for power users
Mobile Experience Responsive design optimization, potential native app
API Integrations Direct Salesforce sync, event platform integration

Champion Portal Phases (Planned)

Phase Focus Timeline
Phase 1 Authentication, Profiles, Directory 8-12 weeks
Phase 2 Events, Stories, Contributions 6-8 weeks
Phase 3 Discussion Boards 4-6 weeks
Phase 4 Messaging & Notifications 4-6 weeks
Phase 5 Advanced Features (Map view, Visit mode) 4-6 weeks
Phase 6 Reporting & Insights 4-6 weeks

10. Risks and Assumptions

Key Technical Risks

Risk Likelihood Impact Mitigation
Performance at scale Medium High Batch processing, caching, query optimization
Data quality issues Medium Medium Preview imports, validation, duplicate detection
Test coverage gaps High Medium Expanding test suite, prioritizing critical paths
Heroku constraints Low Medium Memory optimization, documented in deployment guides
Single point of failure Low High Heroku managed infrastructure, automated backups

Product/Business Risks

Risk Likelihood Impact Mitigation
Low adoption by staff Low High Training, intuitive UX, visible time savings
Data staleness Medium Medium Import workflows, freshness monitoring
Champion program growth Unknown Medium Portal expansion, improved onboarding
Competing priorities Medium Medium Clear roadmap, stakeholder alignment

Dependencies Outside Direct Control

Dependency Risk Contingency
Salesforce data format Contact ID format changes Flexible import parsing
Heroku platform Price changes, deprecations Standard Rails app portable to other hosts
Cloudinary Service interruption Local storage fallback in development
Mailgun Deliverability issues Configurable email provider
Source data quality Upstream systems provide bad data Preview validation catches errors

Stated Assumptions

Assumption Validity Check
Staff will input engagement data regularly Training and workflow documentation
BUID remains stable identifier Core to data model—no current threats
Contact ID format (C-000000000) is Salesforce standard Validated with CRM team
Champion program will grow University commitment to program
Two-portal architecture is appropriate Current design supports this
PostgreSQL can handle growth Suitable for 100K+ alumni, 1M+ activities

11. Glossary

Core Terms

Term Definition
Alumni A person who attended or graduated from Belmont University. Note: “Alumni” is both singular and plural in this application.
BUID Belmont University ID — the unique identifier for each alumni record (e.g., B12345678)
Contact ID A Salesforce-compatible identifier in format C-000000000, used for CRM integration
Engagement Activity Any interaction between an alumnus and the university (event attendance, email click, donation, etc.)
Engagement Score A calculated number representing an alumnus’s overall engagement level based on weighted activities
Champion An alumnus who has completed the champion signup process and serves as a volunteer ambassador
Prospect An alumnus identified as a potential future champion (manually flagged or in signup progress)

Feature-Specific Terms

Term Definition
Activity Cap A limit on how many times certain activities count toward engagement score (prevents gaming)
Distance Formula The combined score calculation: √((score × 1.5)² + (activity_count × 1.0)²)
Engagement Level A tier (0-4) assigned to each activity type determining its point value
Flagship Event A major university event (Homecoming, Reunion, etc.) tracked for follow-up engagement
Fiscal Year July 1 through June 30 — the university’s financial year used for reporting
Top Engaged A ranked list of alumni sorted by their combined engagement distance score

Technical Terms

Term Definition
ActiveRecord The Rails component that handles database interactions
Devise The authentication library managing user login/logout
Hotwire/Turbo The technology enabling partial page updates without full reloads
Import Map Rails feature for loading JavaScript without a bundler
pg_search PostgreSQL full-text search library for fast, flexible queries
Service Object A Ruby class that encapsulates business logic outside controllers
Turbo Frame A container that can be updated independently from the rest of the page

Acronyms

Acronym Expansion
BUID Belmont University ID
BQID BruinQuest ID (same as Contact ID, C-000000000 format)
CLC City Leadership Council — regional champion coordinators
CRM Customer Relationship Management (Salesforce)
CSV Comma-Separated Values — file format for data import/export
L1, L2, L3, L4 Engagement Levels 1-4 (point values: 1, 3, 7, 10)
UI/UX User Interface / User Experience

Role Definitions

Role Description
Admin Full system access including settings, user management, and data imports
Staff Standard operational access to search, view, and update records
Champion External alumni user with access to the Champion Portal (future)
CLC (City Leadership Council) Regional champion coordinator with elevated Champion Portal permissions (future)
Document Purpose
REPO_OVERVIEW.md Complete technical architecture
development/AGENTS.md Developer and AI assistant guide
development/MODEL_RELATIONSHIPS.md Database associations reference
features/ Feature-specific documentation
planning/ Future development specifications
features/AUTH_AND_ROLES_SYSTEM.md Authentication & role system (complete)

This document provides a complete orientation to Alumni Lookup for any stakeholder. For detailed technical implementation, refer to the linked documentation above.