alumni_lookup

Phase 1: Foundations

Champion Portal Development Phase 1

Estimated Effort: 8–12 weeks
Focus: Auth, Profile, Directory, Regional structure, Dashboard

Related Documents:

Table of Contents

  1. Overview
  2. Sub-Phases
  3. Questions to Answer Before Starting
  4. Scope
  5. Definition of Success
  6. Tests to Create
  7. Documentation Updates

1. Overview

Phase 1 establishes the foundation for the Champion Portal. Champions will be able to:

This phase delivers the core identity and discovery features that make Champions feel part of a community from day one.

2. Sub-Phases

Phase 1 is divided into 5 sub-phases that can be implemented incrementally. Each sub-phase is a standalone prompt for an implementation agent.

Sub-Phase Name Prompt Est. Time
1.1 Database & Models “Implement Phase 1.1” 1–2 days
1.2 Email Authentication “Implement Phase 1.2” 1–2 days
1.3 SSO Authentication “Implement Phase 1.3” 1–2 days
1.4 Profile & Directory “Implement Phase 1.4” 2–3 days
1.5 Dashboard & Admin “Implement Phase 1.5” 2–3 days

Sub-Phase 1.1: Database & Models

Goal: Create all database tables and models for Champion Portal foundations.

Status: ✅ COMPLETE (December 5, 2025)

Deliverables:

Implementation Notes:

Migrations Created:

Deployment: After deploying migrations, run seed task on staging/production:

heroku run rails champion_portal:seed_geographic_data --app alumni-lookup-staging

Acceptance Test:

# In rails console:
champion = Cp::Champion.create!(first_name: "Test", last_name: "User", email: "test@example.com", password: "password123")
champion.verification_status # => "unverified"
ZipCode.find_by(zip: "37027").district.name # => "Nashville"
ZipCode.find_by(zip: "37027").district.region.name # => "Southeast"

Sub-Phase 1.2: Email Authentication

Goal: Champions can sign up with email, verify, and log in.

Status: ✅ COMPLETE (December 5, 2025)

Deliverables:

Test Coverage (53 tests, 119 assertions):

Note: SSO buttons deferred to Phase 1.3 due to Devise multi-model OmniAuth path prefix conflict.

Files Created:

Routes Added:

Acceptance Test:

  1. Visit champions.local.test/signup → enter name + email → submit
  2. Receive confirmation email → click link
  3. Set password (min 8 characters) → account now “email_verified”
  4. Log in with email + password → see dashboard
  5. Log out → request password reset → complete reset → log in

Sub-Phase 1.3: SSO Authentication

Goal: Champions can sign up/log in with Google (Apple/Facebook deferred to future enhancement).

Status: ✅ COMPLETE (December 8, 2025)

Deliverables:

Implementation Notes:

Files Created:

Files Modified:

Routes Added:

Acceptance Test:

  1. Visit champions.bualum.dev:3000/login → see “Sign in with Google” at top
  2. Click “Sign in with Google” → authorize with Google → redirected to ZIP prompt
  3. Enter ZIP code → submit → redirected to dashboard
  4. Log out → “Sign in with Google” again → logged in directly to dashboard

Sub-Phase 1.4: Profile & Directory

Goal: Champions can complete profiles and search for other Champions.

Deliverables:

Profile Completion Wizard:

Affinity Selection (Step 4 & Profile Edit):

Profile Edit Page:

Directory:

Export Infrastructure:

Key UX Decisions:

Acceptance Test:

  1. Log in as Email Verified → start profile completion wizard
  2. Complete Step 1 (required) → skip Steps 2-4 → upload photo or skip
  3. Land on dashboard with “Profile incomplete” reminder
  4. Go to Profile Edit → add affinities using search + category browse
  5. Affinities appear on profile page
  6. Attempt to access directory → redirected with “pending verification” message
  7. (Staff verifies account in Lookup Portal)
  8. Refresh → access directory → search by affinity → view another Champion’s profile

Sub-Phase 1.5: Dashboard & Admin

Goal: Champions see personalized dashboard; Staff can verify Champions.

Deliverables:

Acceptance Test:

  1. Champion logs in → sees dashboard with their name, region
  2. Staff logs into Lookup Portal → Verification Queue → sees pending Champions
  3. Staff searches alumni by name → selects match → clicks “Link BUID”
  4. Champion’s status changes to “champion_verified”
  5. Champion can now access directory

3. Questions to Answer Before Starting

3.1 Already Resolved (Tier 1 Decisions)

Question Decision Source
What is the onboarding flow? Progressive Account Creation (name + email first) DECISIONS.md §2.1
Is BUID required at signup? No — Optional + Two-tier verification DECISIONS.md §2.2
What is the account data model? Single cp_champions table with verification_status enum DECISIONS.md §2.3
Which SSO providers? Google, Apple, Facebook DECISIONS.md §2.12
How is location captured? ZIP-first — ZIP → city/state/district/region DECISIONS.md §2.10
How are photos handled? Separate: cp_champions.photo for Champion Portal DECISIONS.md §2.9
Mobile or desktop first? Mobile-first DECISIONS.md §2.5
Table naming convention? cp_ prefix for Champion Portal tables DECISIONS.md §2.6

3.2 Resolved Before Starting (December 4, 2025)

Question Decision Notes
How should ZIP → District mapping be seeded? CSV import — Seed from zip_district_region.csv Rake task: rails champion_portal:seed_geographic_data
What districts/regions exist initially? 820 districts, 7 regions, with 8 highlighted See data details below
How should verification queue be organized in Lookup? New page in Lookup Portal — /admin/champion_verifications Future consideration: Unified admin portal at admin.bualum.co (see BACKLOG.md)
Password requirements? 8+ characters, at least 1 letter and 1 number Balanced security/friction
Session duration? 7 days default, 30 days with “Remember me” Mobile-friendly with security option

Geographic Data (Imported December 5, 2025):

3.3 Needs Clarification from Stakeholders

Question Who Decides Impact
Pilot group composition Engagement Team Which Champions get first access
Verification turnaround SLA Engagement Team User messaging about wait time
Profile fields required vs optional Product/Engagement Onboarding friction
Champion role quiz — required or optional? Product Onboarding flow

4. Scope

4.1 In Scope

Area Deliverables
Authentication Email signup, password reset, email verification, Google/Apple/Facebook SSO
Account model cp_champions table with verification status enum
Profile Personal info, contact info, employment, affinities, photo upload
Privacy controls Per-field visibility settings
Location ZIP-based city/district/region assignment
Directory Search by name, city, grad year, college, major, industry
Dashboard Welcome, role display, quick actions, regional events (placeholder), regional posts (placeholder)
Admin: Verification Engagement Team can search alumni, link BUID to Champion account
Regional structure Districts and regions tables, ZIP mapping

4.2 Out of Scope (Later Phases)

Feature Phase
Event submission/calendar Phase 2
Story submission Phase 2
Mentorship matching Phase 2
Discussion boards Phase 3
Direct messaging Phase 4
Visit mode Phase 5
Map view Phase 5
Reporting dashboards Phase 6

5. Definition of Success

5.1 Core Acceptance Criteria

Criterion Validation
Champion can sign up with email End-to-end test passes
Champion can sign up with Google SSO End-to-end test passes
Champion can sign up with Apple SSO End-to-end test passes
Champion can sign up with Facebook SSO End-to-end test passes
Email verification flow works User receives email, clicks link, can set password
Password reset works User can request and complete reset
Email Verified user can edit own profile Access control enforced
Email Verified user cannot see directory Access control enforced
Champion Verified user can browse directory Directory search returns results
Champion Verified user appears in directory Searchable by name, city, etc.
ZIP code → city/district/region assignment works Auto-populated on profile
Profile changes are logged crm_data_changes records created (unified CRM sync)
Staff can verify Champions in Lookup Portal Verification queue functional
Staff can search alumni and link BUID BUID linking works
Dashboard displays for logged-in Champion Personalized greeting, role, region

5.2 Pilot Success Metrics

Metric Target
Signup completion rate (email verified) >80%
Profile completion rate >70%
Time from signup to Champion Verified <1 business day
Directory searches per pilot user 2+ during pilot

6. Tests to Create

6.1 Model Tests

Model Test Cases
Cp::Champion Valid factory, validation errors, verification status transitions, associations
Cp::Champion ZIP → city/state/district/region lookup
Cp::Champion Photo attachment (ActiveStorage)
Cp::ProfileChange Auto-creates on attribute changes
Cp::ProfileChange Tracks field_name, old_value, new_value, changed_by

6.2 Controller Tests

Controller Test Cases
Cp::RegistrationsController Create account with valid data, reject invalid email, reject duplicate email
Cp::RegistrationsController SSO callback creates account, links existing account
Cp::SessionsController Login with password, login with SSO, logout
Cp::SessionsController Reject unverified users, reject invalid credentials
Cp::ChampionsController Email Verified can edit own profile, cannot edit others
Cp::ChampionsController Champion Verified can view own profile
Cp::DirectoryController Champion Verified can search, Email Verified cannot
Cp::DirectoryController Search by name, city, grad year, college, industry
Cp::DashboardController Returns dashboard for logged-in Champion
Admin::VerificationsController Staff can view queue, search alumni, link BUID

6.3 Feature/Integration Tests

Feature Test Cases
Email signup flow Complete journey: signup → email → verify → set password → profile
Google SSO flow Click Google → authorize → account created → profile completion
Apple SSO flow Click Apple → authorize → account created → profile completion
Facebook SSO flow Click Facebook → authorize → account created → profile completion
Password reset Request reset → email → click link → new password → login
Directory search Log in as Champion Verified → search by name → view profile
Verification workflow Staff logs into Lookup → verification queue → search alumni → link BUID

6.4 Permissions Tests

Scenario Expected Behavior
Unverified user tries to log in Rejected with “verify your email” message
Email Verified user visits directory Redirected with “verification pending” message
Email Verified user edits own profile Allowed
Champion Verified user visits directory Allowed
Non-staff user visits verification queue Rejected (403)

6.5 Data Validation Tests

Data Test Cases
Email Unique, valid format, required
ZIP code Valid 5-digit format, exists in database/lookup
Password Meets complexity requirements
Profile fields Required fields enforced, optional fields nullable

7. Documentation Updates

After completing Phase 1, update the following documents:

7.1 Required Updates

Document Changes
../README.md Mark Phase 1 as complete, update prerequisites
../development/DATA-ARCHITECTURE.md Finalize cp_champions schema, add actual column list
../development/DECISIONS.md Record any new decisions made during implementation
../STAKEHOLDER-OVERVIEW.md Update pilot status
../../features/CHAMPION_PORTAL.md Create implemented feature doc (move from planning)

7.2 New Documentation to Create

Document Purpose
docs/features/CHAMPION_PORTAL.md Document implemented functionality
docs/development/CHAMPION_VERIFICATION_WORKFLOW.md Staff workflow guide
Champion Portal user guide (for pilots) End-user documentation

7.3 Test Fixtures to Add

Fixture Purpose
cp_champions.yml Test champions in various verification states
districts.yml Test districts (Nashville, etc.)
regions.yml Test regions (Southeast, etc.)
zip_codes.yml Test ZIP codes mapped to districts

For detailed specifications on each feature area, see: