Backend to add ranking volunteers, extra volunteer seeds (#84)

## Notion ticket link
<!-- Please replace with your ticket's URL -->
[Admin Matching
Page](https://www.notion.so/uwblueprintexecs/Admin-Dash-Matching-Pages-27210f3fb1dc800aa962c0bb5c09ba15)


<!-- Give a quick summary of the implementation details, provide design
justifications if necessary -->
## Implementation description
* Added a new admin-only endpoint to get all the ranked potential
matches for a given participant
* Added new service methods to query all volunteers and preload all
necessary fields to render

<!-- What should the reviewer do to verify your changes? Describe
expected results and include screenshots when appropriate -->
## Steps to test
1. pdm run seed to get the new seeded volunteers
2. Go onto admin directory and pick a participant
3. Verify all volunteers are ranked on the table


<!-- Draw attention to the substantial parts of your PR or anything
you'd like a second opinion on -->
## What should reviewers focus on?
* 


## Checklist
- [ ] My PR name is descriptive and in imperative tense
- [ ] My commit messages are descriptive and in imperative tense. My
commits are atomic and trivial commits are squashed or fixup'd into
non-trivial commits
- [ ] I have run the appropriate linter(s)
- [ ] I have requested a review from the PL, as well as other devs who
have background knowledge on this PR or who will be building on top of
this PR

---------

Co-authored-by: Yash Kothari <[email protected]>

Author: richieb21

backend/app/routes/auth.py

@@ -24,6 +24,7 @@ async def register_user(user: UserCreateRequest, user_service: UserService = Dep
         "[email protected]",
         "[email protected]",
         "[email protected]",
+        "[email protected]",
     ]
     if user.role == UserRole.ADMIN:
         if user.email not in allowed_Admins:

backend/app/routes/matching.py

@@ -3,7 +3,9 @@
 from fastapi import APIRouter, Depends, HTTPException
 from sqlalchemy.orm import Session
 
-from app.schemas.matching import RelevantUsersResponse
+from app.middleware.auth import has_roles
+from app.schemas.matching import AdminMatchesResponse, RelevantUsersResponse
+from app.schemas.user import UserRole
 from app.services.implementations.matching_service import MatchingService
 from app.utilities.db_utils import get_db
 
@@ -31,3 +33,25 @@ async def get_matches(user_id: UUID, matching_service: MatchingService = Depends
         raise http_ex
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/admin/{participant_id}", response_model=AdminMatchesResponse)
+async def get_admin_matches(
+    participant_id: UUID,
+    matching_service: MatchingService = Depends(get_matching_service),
+    _authorized: bool = has_roles([UserRole.ADMIN]),
+):
+    """
+    Get potential volunteer matches for a participant with full volunteer details for admin view.
+    Returns all volunteers with their complete information (timezone, age, diagnosis, treatments,
+    experiences) and match scores, sorted by score (highest first).
+    """
+    try:
+        matched_data = await matching_service.get_admin_matches(participant_id)
+        return AdminMatchesResponse(matches=matched_data)
+    except ValueError as ve:
+        raise HTTPException(status_code=404, detail=str(ve))
+    except HTTPException as http_ex:
+        raise http_ex
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

backend/app/routes/ranking.py

@@ -1,10 +1,13 @@
 from typing import List
+from uuid import UUID
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
 from app.middleware.auth import has_roles
+from app.models import Experience, Quality, Treatment, User
+from app.models.RankingPreference import RankingPreference
 from app.schemas.user import UserRole
 from app.services.implementations.ranking_service import RankingService
 from app.utilities.db_utils import get_db
@@ -101,6 +104,67 @@ async def get_participant_case(
         raise HTTPException(status_code=500, detail=str(e))
 
 
+class PreferenceItemWithName(BaseModel):
+    kind: str
+    id: int
+    scope: str
+    rank: int
+    name: str
+
+
+@router.get("/preferences/{user_id}", response_model=List[PreferenceItemWithName])
+async def get_ranking_preferences(
+    user_id: str,
+    target: str = Query(..., pattern="^(patient|caregiver)$"),
+    db: Session = Depends(get_db),
+    authorized: bool = has_roles([UserRole.ADMIN]),
+) -> List[PreferenceItemWithName]:
+    """Get ranking preferences for a user (admin only)."""
+    try:
+        user_uuid = UUID(user_id)
+        user = db.query(User).filter(User.id == user_uuid).first()
+        if not user:
+            raise HTTPException(status_code=404, detail="User not found")
+
+        preferences = (
+            db.query(RankingPreference)
+            .filter(RankingPreference.user_id == user_uuid, RankingPreference.target_role == target)
+            .order_by(RankingPreference.rank)
+            .all()
+        )
+
+        result = []
+        for pref in preferences:
+            item_id = None
+            name = None
+            if pref.kind == "quality" and pref.quality_id:
+                item_id = pref.quality_id
+                quality = db.query(Quality).filter(Quality.id == pref.quality_id).first()
+                if quality:
+                    name = quality.label
+            elif pref.kind == "treatment" and pref.treatment_id:
+                item_id = pref.treatment_id
+                treatment = db.query(Treatment).filter(Treatment.id == pref.treatment_id).first()
+                if treatment:
+                    name = treatment.name
+            elif pref.kind == "experience" and pref.experience_id:
+                item_id = pref.experience_id
+                experience = db.query(Experience).filter(Experience.id == pref.experience_id).first()
+                if experience:
+                    name = experience.name
+
+            if item_id is not None and name:
+                result.append(
+                    PreferenceItemWithName(kind=pref.kind, id=item_id, scope=pref.scope, rank=pref.rank, name=name)
+                )
+
+        return result
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
 @router.get("/admin/options", response_model=RankingOptionsResponse)
 async def get_ranking_options_admin(
     user_id: str = Query(..., description="User ID (UUID) to fetch options for"),

backend/app/schemas/matching.py

@@ -2,7 +2,8 @@
 Pydantic schemas for matching-related data validation and serialization.
 """
 
-from typing import List
+from typing import List, Optional
+from uuid import UUID
 
 from pydantic import BaseModel
 
@@ -24,3 +25,29 @@ class RelevantUsersResponse(BaseModel):
     """
 
     matches: List[MatchedUser]
+
+
+class AdminMatchCandidate(BaseModel):
+    """
+    Schema for an admin match candidate with full volunteer details and match score.
+    Used for displaying potential matches in the admin interface.
+    """
+
+    volunteer_id: UUID
+    first_name: Optional[str]
+    last_name: Optional[str]
+    email: str
+    timezone: Optional[str]
+    age: Optional[int]
+    diagnosis: Optional[str]
+    treatments: List[str] = []
+    experiences: List[str] = []
+    match_score: float  # 0-100 scale
+
+
+class AdminMatchesResponse(BaseModel):
+    """
+    Response schema for admin matching endpoint containing a list of match candidates with full details.
+    """
+
+    matches: List[AdminMatchCandidate]

backend/app/seeds/users.py

@@ -344,6 +344,111 @@ def seed_users(session: Session) -> None:
             "loved_one_treatments": [3, 6],  # Chemotherapy, Radiation
             "loved_one_experiences": [3, 4],  # Feeling Overwhelmed, Fatigue
         },
+        # Additional volunteers for testing
+        {
+            "role": "volunteer",
+            "user_data": {
+                "first_name": "James",
+                "last_name": "Wilson",
+                "email": "[email protected]",
+                "auth_id": "auth_james_011",
+                "date_of_birth": date(1990, 3, 20),
+                "phone": "555-0402",
+                "city": "Calgary",
+                "province": "Alberta",
+                "postal_code": "T2P 1J4",
+                "gender_identity": "Man",
+                "pronouns": ["he", "him"],
+                "ethnic_group": ["White/Caucasian"],
+                "marital_status": "Single",
+                "has_kids": "No",
+                "timezone": "MST",
+                "diagnosis": "Non-Hodgkin Lymphoma",
+                "date_of_diagnosis": date(2019, 6, 10),
+                "has_blood_cancer": "yes",
+                "caring_for_someone": "no",
+            },
+            "treatments": [3, 6, 14],  # Chemotherapy, Radiation, BTK Inhibitors
+            "experiences": [1, 3, 4, 7],  # Brain Fog, Feeling Overwhelmed, Fatigue, Returning to work
+        },
+        {
+            "role": "volunteer",
+            "user_data": {
+                "first_name": "Maria",
+                "last_name": "Garcia",
+                "email": "[email protected]",
+                "auth_id": "auth_maria_012",
+                "date_of_birth": date(1988, 8, 15),
+                "phone": "555-0403",
+                "city": "Vancouver",
+                "province": "British Columbia",
+                "postal_code": "V6B 2K1",
+                "gender_identity": "Woman",
+                "pronouns": ["she", "her"],
+                "ethnic_group": ["Hispanic/Latino"],
+                "marital_status": "Married/Common Law",
+                "has_kids": "Yes",
+                "timezone": "PST",
+                "diagnosis": "Acute Myeloid Leukemia",
+                "date_of_diagnosis": date(2021, 1, 8),
+                "has_blood_cancer": "yes",
+                "caring_for_someone": "no",
+            },
+            "treatments": [3, 10],  # Chemotherapy, Autologous Stem Cell Transplant
+            "experiences": [3, 4, 10, 11],  # Feeling Overwhelmed, Fatigue, Anxiety/Depression, PTSD
+        },
+        {
+            "role": "volunteer",
+            "user_data": {
+                "first_name": "Alex",
+                "last_name": "Martinez",
+                "email": "[email protected]",
+                "auth_id": "auth_alex_013",
+                "date_of_birth": date(1992, 11, 5),
+                "phone": "555-0404",
+                "city": "Toronto",
+                "province": "Ontario",
+                "postal_code": "M5H 2N2",
+                "gender_identity": "Non-binary",
+                "pronouns": ["they", "them"],
+                "ethnic_group": ["Hispanic/Latino"],
+                "marital_status": "Single",
+                "has_kids": "No",
+                "timezone": "EST",
+                "diagnosis": "Chronic Myeloid Leukemia",
+                "date_of_diagnosis": date(2020, 9, 12),
+                "has_blood_cancer": "yes",
+                "caring_for_someone": "no",
+            },
+            "treatments": [14, 15],  # BTK Inhibitors, Targeted Therapy
+            "experiences": [1, 10],  # Brain Fog, Anxiety/Depression
+        },
+        {
+            "role": "volunteer",
+            "user_data": {
+                "first_name": "Patricia",
+                "last_name": "Brown",
+                "email": "[email protected]",
+                "auth_id": "auth_patricia_014",
+                "date_of_birth": date(1985, 4, 18),
+                "phone": "555-0405",
+                "city": "Montreal",
+                "province": "Quebec",
+                "postal_code": "H3B 1M8",
+                "gender_identity": "Woman",
+                "pronouns": ["she", "her"],
+                "ethnic_group": ["Black/African"],
+                "marital_status": "Married/Common Law",
+                "has_kids": "Yes",
+                "timezone": "EST",
+                "diagnosis": "Multiple Myeloma",
+                "date_of_diagnosis": date(2019, 11, 22),
+                "has_blood_cancer": "yes",
+                "caring_for_someone": "no",
+            },
+            "treatments": [3, 10, 11],  # Chemotherapy, Autologous Stem Cell Transplant, Allogeneic Stem Cell Transplant
+            "experiences": [1, 3, 4, 5, 7],  # Brain Fog, Feeling Overwhelmed, Fatigue, Sleep Issues, Returning to work
+        },
     ]
 
     created_users = []

backend/app/services/implementations/matching_service.py

@@ -5,7 +5,7 @@
 from uuid import UUID
 
 from fastapi import HTTPException
-from sqlalchemy.orm import Session
+from sqlalchemy.orm import Session, joinedload
 
 from app.interfaces.matching_service import IMatchingService
 from app.models.Experience import Experience
@@ -99,6 +99,96 @@ async def get_matches(self, participant_id: UUID, limit: Optional[int] = 5) -> L
             self.logger.error(f"Error finding matches: {str(e)}")
             raise HTTPException(status_code=500, detail=f"Internal server error during matching process: {str(e)}")
 
+    async def get_admin_matches(self, participant_id: UUID) -> List[Dict[str, Any]]:
+        """
+        Get potential volunteer matches for a participant with full volunteer details for admin view.
+        Returns all volunteers with their complete information and match scores.
+        :param participant_id: ID of the participant user to find matches for
+        :return: List of dictionaries with full volunteer details and match scores
+        :raises ValueError: If user is not found or not a participant
+        """
+        try:
+            # Get the participant user
+            user = self.db.query(User).filter(User.id == participant_id).first()
+            if not user:
+                raise ValueError(f"User with ID {participant_id} not found")
+
+            if user.role.name != UserRole.PARTICIPANT:
+                raise ValueError(f"User with ID {participant_id} is not a participant")
+
+            participant_data = self.db.query(UserData).filter(UserData.user_id == participant_id).first()
+            if not participant_data:
+                raise ValueError(f"User with ID {participant_id} has no intake form data")
+
+            participant_preferences = self._get_user_preferences(participant_id)
+            if not participant_preferences:
+                raise ValueError(f"User with ID {participant_id} has no ranking form data")
+
+            # Get all active, approved volunteers with their data and relationships
+            # Eagerly load user_data, treatments, and experiences to avoid N+1 queries
+            volunteers = (
+                self.db.query(User)
+                .join(User.role)
+                .options(
+                    joinedload(User.user_data).joinedload(UserData.treatments),
+                    joinedload(User.user_data).joinedload(UserData.experiences),
+                )
+                .filter(Role.name == UserRole.VOLUNTEER)
+                .filter(User.active)
+                .filter(User.approved)
+                .all()
+            )
+
+            if not volunteers:
+                return []
+
+            # Calculate scores and build detailed responses
+            scored_volunteers = []
+            for volunteer_user in volunteers:
+                volunteer_data = volunteer_user.user_data
+                if not volunteer_data:
+                    continue
+                score = self._calculate_match_score(participant_data, volunteer_data, participant_preferences)
+
+                # Calculate age from date_of_birth
+                age = None
+                if volunteer_data.date_of_birth:
+                    today = date.today()
+                    age = today.year - volunteer_data.date_of_birth.year
+                    # Adjust if birthday hasn't occurred this year
+                    if (today.month, today.day) < (
+                        volunteer_data.date_of_birth.month,
+                        volunteer_data.date_of_birth.day,
+                    ):
+                        age -= 1
+
+                treatment_names = [treatment.name for treatment in volunteer_data.treatments]
+
+                experience_names = [experience.name for experience in volunteer_data.experiences]
+
+                match_candidate = {
+                    "volunteer_id": volunteer_user.id,
+                    "first_name": volunteer_user.first_name,
+                    "last_name": volunteer_user.last_name,
+                    "email": volunteer_user.email,
+                    "timezone": volunteer_data.timezone,
+                    "age": age,
+                    "diagnosis": volunteer_data.diagnosis,
+                    "treatments": treatment_names,
+                    "experiences": experience_names,
+                    "match_score": round(score * 100, 2),
+                }
+                scored_volunteers.append((match_candidate, score))
+
+            scored_volunteers.sort(key=lambda x: x[1], reverse=True)
+            return [candidate for candidate, _ in scored_volunteers]
+
+        except ValueError as ve:
+            raise ve
+        except Exception as e:
+            self.logger.error(f"Error finding admin matches: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Internal server error during matching process: {str(e)}")
+
     def _get_user_preferences(self, user_id: UUID) -> List[Dict[str, Any]]:
         """Get user's ranking preferences with full context."""
         preferences = (

backend/app/services/implementations/user_service.py

@@ -60,8 +60,8 @@ async def create_user(self, user: UserCreateRequest) -> UserCreateResponse:
 
             # Create user in database
             db_user = User(
-                first_name=user.first_name or "",
-                last_name=user.last_name or "",
+                first_name=user.first_name if user.first_name else None,
+                last_name=user.last_name if user.last_name else None,
                 email=user.email,
                 role_id=role_id,
                 auth_id=firebase_user.uid,