alumni_lookup

Alumni Lookup Documentation

Last Updated: December 2025
Comprehensive documentation for the Alumni Lookup application.

📚 Quick Start

Document	Purpose	Audience
PRODUCT_OVERVIEW.md	Stakeholder-ready product summary	Everyone
REPO_OVERVIEW.md	Technical architecture and codebase	Developers
CHANGELOG.md	Version history and release notes	Everyone
../README.md	Setup and getting started	New developers

📁 Documentation Structure

docs/
├── PRODUCT_OVERVIEW.md      # Stakeholder-ready product summary
├── REPO_OVERVIEW.md         # Technical architecture overview
├── CHANGELOG.md             # Version history
├── README.md                # This file - documentation index
│
├── development/             # Technical guides for contributors
│   ├── AGENTS.md            # AI assistant & developer guide
│   ├── ARCHITECTURE.md      # Two-domain architecture
│   ├── AUTHENTICATION.md    # Devise setup & auth patterns
│   ├── PERMISSIONS_MATRIX.md # Role-based access blueprint
│   ├── API.md               # Internal API documentation
│   ├── MODEL_RELATIONSHIPS.md # ActiveRecord associations
│   ├── TESTING_GUIDE.md     # Test patterns, fixtures & coverage
│   ├── FEATURE_FLAGS.md     # Feature flag strategy & usage
│   ├── TODO_BUGS.md         # Known issues tracker
│   ├── DOCUMENTATION_STANDARDS.md # Templates for new docs
│   ├── TAILWIND_PLUS_ELEMENTS.md # UI component guide
│   ├── TAILWIND_PLUS_ELEMENTS_DOCS.md # Component reference
│   └── UNIFIED_CRM_SYNC.md      # CRM change tracking architecture
│
├── features/                # Feature-specific documentation
│   ├── AFFINAQUEST_IMPORT.md # CRM contact sync & import
│   ├── AUTH_AND_ROLES_SYSTEM.md # Authentication & roles v1.3.0 (complete)
│   ├── CHAMPION_SIGNUP_SYSTEM.md # Champion signup v1.0 (complete)
│   ├── ENGAGEMENT_STATS_SYSTEM.md # Analytics dashboard
│   ├── TOP_ENGAGED_ALUMNI_SYSTEM.md # Ranking algorithm
│   ├── FLAGSHIP_EVENTS.md   # Event tracking
│   ├── ALUMNI_CONTACT_ID_INTEGRATION.md # Salesforce integration
│   ├── ALUMNI_PHOTOS_FEATURE.md # Photo uploads
│   ├── DEGREE_UPLOAD_PREVIEW.md # Degree imports
│   └── ACCENT_INSENSITIVE_SEARCH.md # Search enhancement
│
├── deployment/              # Service-specific setup guides
│   └── PHOTO_STORAGE_SETUP.md   # S3 / Cloudinary config for photos
│
├── operations/              # Environment & deployment pipelines
│   ├── DEPLOY_GUIDE.md            # Quick deployment instructions
│   ├── ENVIRONMENTS_CURRENT.md    # Current state analysis
│   ├── ENVIRONMENT_STRATEGY.md    # Target environment design
│   ├── EXTERNAL_SERVICES_ENV_CONFIG.md # Service config per env
│   ├── CI_PIPELINE.md             # GitHub Actions CI/CD
│   └── DEPLOYMENT_PIPELINE.md     # Deploy & rollback procedures
│
└── planning/                # Future development (NOT YET IMPLEMENTED)
    ├── README.md            # Planning docs overview
    ├── champion-portal/           # Champion Portal specifications
    └── event-checkin-integration/  # Event check-in integration plan
        ├── 00-overview.md           # Problem, goals, recommendation
        ├── 01-pros-cons-and-questions.md  # Analysis & decisions
        ├── 02-phased-integration-plan.md  # Development roadmap
        └── 03-champion-portal-interaction.md  # Portal alignment

🔍 Find Documentation By Task

Understanding the Product

PRODUCT_OVERVIEW.md — What, who, why, features, architecture
REPO_OVERVIEW.md — Technical deep-dive for developers

Setting Up Development

../README.md — Clone, install, configure
development/AGENTS.md — Conventions and patterns
development/MODEL_RELATIONSHIPS.md — Database associations

Working with Features

features/ENGAGEMENT_STATS_SYSTEM.md — Scoring and analytics
features/CHAMPION_SIGNUP_SYSTEM.md — Champion flow (v1.0)
features/TOP_ENGAGED_ALUMNI_SYSTEM.md — Ranking algorithm

Importing/Exporting Data

features/AFFINAQUEST_IMPORT.md — CRM contact sync with recency-aware updates
features/DEGREE_UPLOAD_PREVIEW.md — Degree imports
features/ALUMNI_CONTACT_ID_INTEGRATION.md — CRM integration
features/CHAMPION_SIGNUP_SYSTEM.md — Champion CSV import/export

Deploying to Production

operations/DEPLOY_GUIDE.md — Quick deployment instructions
operations/DEPLOYMENT_PIPELINE.md — Deploy workflows, rollbacks, smoke tests
deployment/PHOTO_STORAGE_SETUP.md — S3 / Cloudinary for photos

Setting Up Environments & CI/CD

operations/ENVIRONMENTS_CURRENT.md — Current state
operations/ENVIRONMENT_STRATEGY.md — Environment design
operations/EXTERNAL_SERVICES_ENV_CONFIG.md — Service config per env
operations/CI_PIPELINE.md — GitHub Actions workflows

Debugging Issues

development/TODO_BUGS.md — Known issues
development/AGENTS.md — Common errors and solutions
development/MODEL_RELATIONSHIPS.md — Association troubleshooting

Planning Future Work

planning/README.md — Future development overview
features/AUTH_AND_ROLES_SYSTEM.md — Complete authentication & role system
planning/champion-portal/ — Champion Portal specifications
planning/event-checkin-integration/ — Event check-in integration plan

🔑 Quick Reference

Engagement Scoring

Level 0 → 0 points    Level 1 → 1 point     Level 2 → 3 points
Level 3 → 7 points    Level 4 → 10 points

Activity Caps: email_click (max 5), event_rsvp (max 2)
Distance Formula: √((score × 1.5)² + (activity_count × 1.0)²)

Critical Model Associations

# ✅ CORRECT
EngagementActivity.joins(:alumni)  # NOT :alumnus
Alumni.joins(degrees: { major: :college })  # Full chain required

# ❌ WRONG
EngagementActivity.joins(:alumnus)  # Wrong name
Alumni.joins(degrees: :college)  # Skips major

Contact ID Format

Pattern: C-000000000 (e.g., C-000198612)
Export Header: "AdvRM - Contact ID"

📝 Contributing to Documentation

When to Update Docs

Change Type	Update These Files
New feature	Create in `features/`, update this README
Bug fix	Add to `CHANGELOG.md`, update `TODO_BUGS.md`
Architecture change	Update `development/ARCHITECTURE.md`
Model changes	Update `development/MODEL_RELATIONSHIPS.md`
New patterns	Update `development/AGENTS.md`

Documentation Standards

See development/DOCUMENTATION_STANDARDS.md for:

Templates for new feature documentation
Bug fix documentation format
Checklist for documentation updates

Principles

Single Source of Truth — Document each concept in ONE place
Keep Current — Update during development, not after
Cross-Reference — Link related docs, don’t duplicate
Actionable — Include code examples and steps

🔗 External References

GitHub Copilot Config: ../.github/copilot-instructions.md
Rails Guides: https://guides.rubyonrails.org/
Tailwind CSS: https://tailwindcss.com/docs