alumni_lookup

Alumni Lookup & Alumni Network — Product Overview

Canonical sources: Portal philosophy, posture, and language live in /docs/planning/champion-portal/source/README.md.
Use these sources (including CHRIST_CENTERED__IDENTITY_STATEMENT.md) when writing specs or user-facing copy. Prefer quoting/paraphrasing over inventing new language.

Version: 2.0
Last Updated: February 2026
Audience: Consumers, Product Managers, Engineers, Designers, Stakeholders

---

Table of Contents

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

---

1. Product Summary

What It Is

This application is a two-portal platform serving Belmont University’s alumni engagement ecosystem:

Portal	Domain	Purpose
Alumni Lookup	alumnilookup.com	Internal staff portal for alumni engagement tracking
Alumni Network	belmontalum.com	External alumni community platform

Alumni Lookup helps staff track, measure, and grow alumni engagement through search, scoring, analytics, and data import/export tools. Alumni Network provides alumni with a digital home to connect, discover communities, find career resources, and engage with Belmont.

Both portals share a single Rails application and PostgreSQL database.

Who It Serves

• Alumni Engagement Staff — Search, track, and manage alumni relationships daily (Lookup Portal)
• University Administrators — Visibility into engagement metrics and program effectiveness (Lookup Portal)
• Portal Admins — Manage champion program, verify accounts, assign community leaders (Lookup Portal: Champions admin)
• Alumni (Members) — Browse directory, join communities, connect with peers, submit content (Alumni Network)
• Alumni (Champions) — Opt-in volunteers with role-specific daily engagement ideas (Alumni Network)
• Community Leaders — Moderate discussions, pin announcements, coordinate communities (Alumni Network)

The Core Problem It Solves

Lookup Portal: Universities struggle to understand which alumni are truly engaged versus merely present in their database. Alumni Lookup transforms passive contact records into actionable engagement intelligence—helping staff identify top supporters, discover untapped potential, and measure outreach effectiveness.

Alumni Network: Alumni lose connection with their university after graduation, with no easy way to find fellow Bruins, stay engaged, or contribute. The Alumni Network provides an always-on digital home that serves three tiers of engagement—from casual browsing to active community leadership.

---

2. Value Proposition

For Alumni Engagement Staff (Lookup Portal)

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
Managing champion signups manually	Automated pipeline with status tracking and verification

For Alumni (Alumni Network)

Before	After
No way to find fellow Bruins	Directory with search by district, year, college, industry
No sense of belonging after graduation	Community membership by geography, major, affinity, industry
No way to hear from or share news	News feed and event listings; submit your own content
No career support after graduating	Career center with resources, events, and connections
No recognition for staying engaged	Champion role system with daily engagement ideas
No way to connect with specific alumni	Connection requests with three intent types (Say Hi, Career, Networking)

For Engineers/Technical Stakeholders

Technical Value	Details
Modern Stack	Ruby on Rails 7.1, PostgreSQL, Tailwind CSS, Hotwire
Clean Architecture	Service objects (49), RESTful controllers (99), namespaced code
Smart Search	PostgreSQL full-text search with unaccent extension
Performance	Caching strategies, batch processing, query optimization
Maintainability	210+ Minitest tests, comprehensive documentation, AI-friendly conventions
Scale	Two-portal architecture with shared database; 76 models, 169 migrations

---

3. Core Features — Lookup Portal

3.1 Alumni Search & Management

Instant access to alumni records with powerful search across names, degrees, locations, and engagement status. Accent-insensitive matching via PostgreSQL unaccent extension. Composable filters with pagination.

3.2 Engagement Scoring System

Automatic engagement scores for every alumnus based on weighted activities (Levels 0–4, capped per activity type). Distance formula: √((score × 1.5)² + (activity_count × 1.0)²). Prevents gaming via per-type caps.

3.3 Top Engaged Alumni Rankings

Rankings by combined engagement score and activity breadth. Time period filtering (30 days, 6 months, 1 year, all time). Exportable to CSV with CRM-ready Contact IDs.

3.4 Engagement Stats Dashboard

Six-tab analytics dashboard:

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

Champion pipeline tracking from prospect identification through signup completion. 5-stage status tracking (started → zip_code complete). Manual prospect flagging. Visual status indicators (color-coded borders). Champions admin namespace (/champions/) for staff.

3.6 Data Import/Export System

Bulk import for degrees, engagement activities, alumni lists, and Affinaquest contacts. Three-step workflow: upload → preview → commit. Case-insensitive header matching. Auto-creates missing records. CRM-ready exports with Contact ID (C-000000000).

3.7 Settings & Administration

Settings namespace (/settings/) for managing reference data: colleges, majors, districts, affinities, engagement activities, users, current students. Affinaquest CRM integration.

3.8 Tools

Utility tools: batch alumni search, event RSVP converter.

---

4. Core Features — Alumni Network

Full planning details: See planning/champion-portal/README.md

4.1 Authentication & Accounts

Progressive signup (name + email first, then profile wizard). Google OAuth SSO. Email verification. Two-tier verification: email-verified (limited) → champion-verified (full, staff-linked to BUID).

4.2 Profiles & Directory

Multi-step profile wizard (personal info → photo → affinity selection → confirmation). Privacy controls. Directory search by district, graduation year, college, industry. “Champions Like You” recommendations. Profile completion tracking.

4.3 Communities

Seven community types: District, College, Major, Affinity, Industry, Custom, National. Dynamic creation when 3+ alumni share an attribute. Community landing pages with members, discussions, news, events.

4.4 Connections & Messaging

Connection requests with three intent types (Say Hi, Career Advice, Networking). Connection-gated messaging: must connect before messaging. Thread-based conversations with emoji reactions. Settings and rate caps.

4.5 Discussion Boards

Per-community and national boards. Threaded comments with real-time updates. Reactions (emoji). Community Leader moderation (pin, remove, moderate). Seeded questions to spark engagement. Anonymous flagging.

4.6 Events & News

Admin-created events with community targeting. Alumni event submissions (staff-reviewed). District/community-targeted news announcements. Alumni news submissions with attribution.

4.7 Content Submissions

Alumni submit news and events for staff review. Admin review queue with approve/decline/conversation. Attribution to submitting alumni. Content Submission Threads for staff-alumni dialogue.

4.8 Career Center

Public self-serve career hub (accessible without login). Downloadable resources organized by category. Career event listings. OCPD (Office of Career & Professional Development) partnership.

4.9 Champion Role Card

Discovery quiz matching alumni to one of four roles: Community Builder, Connection Advisor, Digital Ambassador, Giving Advocate. Daily engagement idea packs (3/day, role-aligned). 115 seed ideas. Admin CRUD for ideas.

4.10 Notifications & Digests

In-app bell icon notifications. Email digests (daily/weekly, configurable). Per-type notification preferences. Discussion triggers (new posts, replies, mentions).

4.11 Photo Albums

Admin-managed photo albums with gallery lightbox. Dashboard carousel. Community-targeted albums.

4.12 Help & Settings

FAQ with search. Account settings (email, password, privacy). Notification preference management.

---

5. System Architecture Overview

Two-Portal Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                     ALUMNI LOOKUP + ALUMNI NETWORK                       │
├─────────────────┬───────────────────────────────────────────────────────┤
│  LOOKUP PORTAL  │              ALUMNI NETWORK                           │
│  alumnilookup   │              belmontalum                              │
│  .com           │              .com                                     │
│                 │                                                       │
│  Staff roles:   │  Alumni tiers:                                        │
│  Admin          │  Community Leader (~1%)                               │
│  Portal Admin   │  Champion (~10%)                                      │
│  Staff          │  Member (100%)                                        │
│                 │                                                       │
│  Namespaces:    │  Namespaces:                                          │
│  root, settings │  cp/ (external)                                       │
│  champions/     │                                                       │
│  api/, tools/   │                                                       │
├─────────────────┴───────────────────────────────────────────────────────┤
│                       SHARED INFRASTRUCTURE                              │
│  Rails 7.1 │ PostgreSQL │ Hotwire │ Tailwind │ Solid Queue │ Devise    │
│  ActiveStorage │ ActionText │ PgSearch │ Import Maps │ Kaminari        │
└─────────────────────────────────────────────────────────────────────────┘

Domain Routing

Requests are routed by domain:

• *.alumnilookup.com → Lookup Portal controllers
• *.belmontalum.com → Cp:: namespace controllers
• Shared models & services accessed by both portals

Key Integrations

Integration	Purpose	Portal
Cloudinary	Image hosting and transforms	Both
Mailgun	Transactional email, notifications	Both
Salesforce	CRM sync via Contact ID	Lookup
Google OAuth	SSO for alumni registration	Network
PostgreSQL Extensions	unaccent for search	Both

Controller Namespaces

Namespace	Count	Purpose
Root	~15	Lookup Portal core (search, stats, people)
settings/	~10	Reference data management
champions/	~20	Champion admin tools (staff)
cp/	~35	Alumni Network (external)
api/	~8	Internal API endpoints
tools/	~4	Utility tools

---

6. Data Model Overview

Codebase Scale

Component	Count
Models	76
Controllers	99
Services	49
Helpers	25
Mailers	12
Jobs	17
Stimulus controllers	87
Migrations	169
Tests	210

Primary Entities — Lookup Portal

Entity	Purpose	Key Fields
Alumni	Core alumni records	buid (unique), name, contact, contact_id (Salesforce)
Degree	Academic credentials	degree_code, degree_date, major_code
Major	Academic majors	major_code, major_desc
College	Academic colleges	college_code
EngagementActivity	Individual interactions	activity_code, engagement_date
EngagementType	Activity definitions	code, level (0-4), champion_role
ChampionSignup	Champion pipeline	status (1-5), role, interests
User	System users (Devise)	role (staff, portal_admin, admin)

Primary Entities — Alumni Network (Cp:: namespace)

Entity	Purpose	Key Fields
Cp::Champion	Alumni accounts (all portal members, not just Champions — see note below)	email, verification_status, buid, primary_role
Cp::Community	Community groups	community_type, name, slug
Cp::Connection	Alumni connections	champion_id, connected_champion_id
Cp::ConnectionRequest	Connection requests	intent_type, status
Cp::BoardPost	Discussion posts	board_type, community_id, champion_id
Cp::BoardComment	Discussion replies	board_post_id, champion_id
Cp::Event	Community events	starts_at, targeting communities
Cp::NewsPost	News announcements	District/community targeting
Cp::Message	Direct messages	message_thread_id, champion_id
Cp::Notification	In-app notifications	notification_type, read_at
Cp::CareerResource	Career center resources	category, downloadable
Cp::ContentSubmissionThread	Alumni submissions	News/event review workflow
Cp::RoleIdea	Daily engagement ideas	champion_role, category
Cp::ClcAssignment	CL assignments	champion_id, community_id
Cp::SeededQuestion	Discussion starters	Admin-managed, community-targeted

Relationship Chain

College → Major → Degree → Alumni → EngagementActivity → EngagementType
                    ↓
              ChampionSignup
                    ↓
            Cp::Champion ←→ Cp::Community (via ChampionCommunity)
                  ↓
        Cp::Connection, Cp::BoardPost, Cp::Message, Cp::Notification

---

7. User Journeys

Journey 1: Staff Searches for Alumni (Lookup Portal)

1. Navigate to Alumni Search
2. Enter filters: City, Grad Year range, Engagement level
3. See paginated results with scores, degrees, champion status
4. Click alumni for full profile with activity history
5. Export filtered list to CSV with Salesforce Contact IDs

Time: 2-3 minutes vs. 30-45 minutes manually.

Journey 2: Admin Imports Engagement Data (Lookup Portal)

1. Format CSV with buid, activity_code, description, engagement_date
2. Upload → system auto-detects headers
3. Preview: X records ready, Y errors
4. Commit → processed in batches. Summary: imported/skipped with reasons

Time: 10-15 minutes vs. 2-4 hours manually.

Journey 3: Alumni Joins and Explores (Alumni Network)

1. Registers with email/password or Google SSO
2. Confirms email, sets password
3. Completes profile wizard (location, profession, photo, affinities)
4. Auto-joined to communities based on district, college, major
5. Browses directory, sends connection requests
6. Reads news, joins discussions, discovers career resources
7. Optionally selects a Champion role (via quiz or manual selection) for daily engagement ideas

Journey 4: Community Leader Moderates (Alumni Network)

1. Staff assigns CL role to a champion via admin panel
2. CL sees moderation tools on assigned community pages
3. Pins important posts, removes inappropriate content
4. Reviews flagged items, adds moderator notes
5. Coordinates community activity, posts announcements

---

8. Operational Model

Hosting & Infrastructure

Area	Approach
Hosting	Heroku (1 worker, 3 threads)
Database	PostgreSQL (Heroku managed)
Backups	Heroku automated daily
Image Storage	Cloudinary (production), ActiveStorage local (development)
Background Jobs	Solid Queue
Email	Mailgun (transactional + digests)
Caching	Rails cache with configurable TTLs

Teams and Roles

Role	Responsibilities
Alumni Engagement Staff	Daily search, research, prospect management (Lookup)
Portal Admin	Champion verification, CL assignment, content review
Admin	Full system access, user management, settings
Developer	Feature development, deployments, performance

Key Workflows

• Data Import: Source export → CSV formatting → Preview → Commit → Cache refresh
• Champion Pipeline: Prospect flagging → Signup tracking → Verification → Community assignment
• Content Review: Alumni submission → Staff review → Approve/decline → Published
• Notifications: Trigger event → Notification record → Bell icon + optional email digest

---

9. Metrics and Success Criteria

Product Metrics

Metric	Description	Target
Active Staff Users	Staff logging in weekly	100% of engagement team
Alumni Registrations	New Alumni Network accounts	Growing month-over-month
Connection Rate	Connection requests sent → accepted	Track baseline
Community Activity	Discussion posts per community	Weekly activity
Champion Conversion	Role quiz completions	10%+ of members
Content Submissions	Alumni news/event submissions	Growing
Data Freshness	Days since last engagement import	< 7 days

Technical Metrics

Metric	Description	Target
Availability	Uptime	99.5%+
Response Time	Page load	< 2 seconds
Search Performance	Query response	< 500ms
Test Coverage	Tests passing	210+ tests, 0 failures
Error Rate	Application errors/day	< 5

---

10. Roadmap Snapshot

Alumni Network Phase Status

Phase	Focus	Status
1	Foundations (auth, profiles, directory, messaging, events, news, communities)	✅ Complete
1C	Role Selection & Quiz	✅ Complete
2	Community Leadership	✅ Complete
3	Discussion Boards	✅ Complete
4	Mobile-First Cleanup	✅ Complete
5	Pre-MVP Updates	✅ Complete
6	Reporting & Insights	🔶 Partial (activity metrics done; community health remaining)
7	Career Center	✅ Complete
8	Notifications & Digests	✅ Complete
9	Onboarding & UX	🔶 In Progress (email drip remaining)
10	Connections	✅ Complete
11	Champion Role Card	✅ Complete
12	Source-Alignment Review	✅ Complete
13	Progressive Dashboard & Engagement Tiers	📋 Planning
14	Content Submissions	✅ Complete

Lookup Portal

The Lookup Portal is stable and feature-complete for current needs. Ongoing improvements include:

• Settings namespace for reference data management
• Batch tools and API endpoints
• Affinaquest CRM integration
• Performance optimization for large datasets

---

11. Risks and Assumptions

Key Risks

Risk	Likelihood	Impact	Mitigation
Performance at scale	Medium	High	Batch processing, caching, 15s timeout protection
Data quality	Medium	Medium	Preview imports, validation, duplicate detection
Heroku memory	Medium	Medium	1 worker / 3 threads, memory-optimized queries
Adoption	Low	High	Trust-first access, frictionless signup, mobile-first UX

Key Assumptions

Assumption	Status
Two-portal architecture is appropriate	✅ Proven — both portals operational
BUID remains stable identifier	✅ No current threats
PostgreSQL handles scale	✅ Suitable for 50K+ alumni, 1M+ activities
Mobile-first is correct approach	✅ Validated via usage patterns
Alumni want a digital community	Testing — Network launched, adoption being measured

---

12. Glossary

Core Terms

Term	Definition
Alumni	A person who attended or graduated from Belmont University (singular and plural)
BUID	Belmont University ID — unique identifier for each alumni record
BQID	BruinQuest ID — same as Contact ID, format C-000000000
Contact ID	Salesforce-compatible identifier (format C-000000000) for CRM integration
Engagement Activity	Any tracked interaction between an alumnus and the university
Engagement Score	Calculated number representing overall engagement based on weighted activities
Champion	An alumnus who has selected a Champion role (via quiz or manual selection); recognition, not a gated title
Community Leader	A champion promoted by staff to moderate assigned communities
District	A metro area community (Nashville, Atlanta, etc.) — user-facing geographic term

Role Definitions

Role	Portal	Description
Admin	Lookup	Full system access including settings, user management
Portal Admin	Lookup	Staff + champion admin, verification, CL assignment
Staff	Lookup	Standard operational access to search, view, update
Community Leader	Network	Alumni with moderation permissions on assigned communities
Champion	Network	Alumni who selected a Champion role (opt-in recognition)
Member	Network	Any registered, verified alumnus (default tier)

Cp::Champion Naming Caveat: The Cp::Champion model represents ALL portal members (Members, Champions, and Community Leaders). The app was originally built for Champions before expanding to all alumni. To find true “Champions” (those who opted into a role), filter on primary_role present: Cp::Champion.verified.where.not(primary_role: [nil, ""]). Instance check: champion.has_champion_role?.

Technical Terms

Term	Definition
Cp::	Ruby namespace for Alumni Network models, services, and controllers
champions/	Controller namespace for staff-facing champion admin tools
cp/	Controller namespace for external Alumni Network
Hotwire/Turbo	Rails technology for partial page updates without full reloads
Stimulus	JavaScript framework for adding behavior to HTML (87 controllers)
Import Map	Rails feature for loading JavaScript without a bundler
Solid Queue	Background job processor for emails, notifications, async tasks
ActiveStorage	Rails framework for file uploads (photos, resources)
ActionText	Rails rich text editing (Trix editor) in discussions, content

---

Related Documentation

Document	Purpose
REPO_OVERVIEW.md	Complete technical architecture and codebase reference
planning/champion-portal/README.md	Alumni Network technical overview
planning/champion-portal/STAKEHOLDER-OVERVIEW.md	Stakeholder summary and roadmap
planning/champion-portal/JOBS-TO-BE-DONE.md	User motivations and prioritization
development/MODEL_RELATIONSHIPS.md	Database associations reference
features/	Feature-specific documentation
planning/champion-portal/source/	Canonical source documents

---

This document provides a complete orientation to the Alumni Lookup + Alumni Network platform. For detailed Alumni Network planning, see the planning/champion-portal/ directory.