Add automatic match completion service with scheduled job (#90)

- Add MatchCompletionService to auto-complete matches 30 minutes after
call starts
- Integrate APScheduler to run completion job every 15 minutes
- Mark completed matches as soft-deleted (deleted_at set)
- Add apscheduler dependency to pyproject.toml
- Job runs at :00, :15, :30, :45 every hour
- Idempotent design - safe to run multiple times

## Notion ticket link
<!-- Please replace with your ticket's URL -->
[Ticket
Name](https://www.notion.so/uwblueprintexecs/Task-Board-db95cd7b93f245f78ee85e3a8a6a316d)


<!-- Give a quick summary of the implementation details, provide design
justifications if necessary -->
## Implementation description
* 


<!-- What should the reviewer do to verify your changes? Describe
expected results and include screenshots when appropriate -->
## Steps to test
1.


<!-- 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

Author: YashK2005

backend/app/server.py

@@ -2,6 +2,7 @@
 from contextlib import asynccontextmanager
 from typing import Union
 
+from apscheduler.schedulers.background import BackgroundScheduler
 from dotenv import load_dotenv
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
@@ -24,6 +25,7 @@
     user_data,
     volunteer_data,
 )
+from .services.implementations.match_completion_service import MatchCompletionService
 from .utilities.constants import LOGGER_NAME
 from .utilities.firebase_init import initialize_firebase
 from .utilities.ses.ses_init import ensure_ses_templates
@@ -55,7 +57,36 @@ async def lifespan(_: FastAPI):
     ensure_ses_templates()
     models.run_migrations()
     initialize_firebase()
+
+    # Initialize and start the background scheduler for match completion
+    # IMPORTANT: This scheduler runs in-process. When using uvicorn with --reload or multiple
+    # workers (--workers N), each process will spawn its own scheduler, causing duplicate job
+    # execution. For production, either:
+    #   1. Run with a single worker (recommended for this app): uvicorn app.server:app --workers 1
+    #   2. Use a distributed task queue (Celery + Redis) for multi-worker deployments
+    #   3. Use a distributed lock mechanism to ensure only one process runs the job
+    # The auto-completion logic is idempotent, so duplicate runs are safe but wasteful.
+    scheduler = BackgroundScheduler()
+    match_completion_service = MatchCompletionService()
+
+    # Schedule match auto-completion job to run every 15 minutes at fixed times (:00, :15, :30, :45)
+    scheduler.add_job(
+        match_completion_service.auto_complete_matches,
+        trigger="cron",
+        minute="0,15,30,45",  # Run at :00, :15, :30, :45 every hour
+        id="auto_complete_matches",
+        name="Auto-complete matches after scheduled calls",
+        replace_existing=True,
+    )
+
+    scheduler.start()
+    log.info("Background scheduler started - match auto-completion job runs at :00, :15, :30, :45 every hour")
+
     yield
+
+    # Shutdown scheduler gracefully
+    log.info("Shutting down scheduler...")
+    scheduler.shutdown()
     log.info("Shutting down...")
 
 

backend/app/services/implementations/match_completion_service.py

@@ -0,0 +1,85 @@
+"""Service for automatically completing matches after their scheduled calls."""
+
+import logging
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import select, update
+from sqlalchemy.orm import Session
+
+from app.models.Match import Match
+from app.models.MatchStatus import MatchStatus
+from app.models.TimeBlock import TimeBlock
+from app.utilities.constants import LOGGER_NAME
+from app.utilities.db_utils import SessionLocal
+
+
+class MatchCompletionService:
+    """Service to automatically complete matches after their scheduled call time."""
+
+    def __init__(self):
+        self.logger = logging.getLogger(LOGGER_NAME("match_completion_service"))
+
+    def auto_complete_matches(self) -> None:
+        """
+        Find all confirmed matches where the scheduled call ended 30+ minutes ago
+        and mark them as completed and soft-deleted.
+
+        Uses a set-based UPDATE query for efficiency and atomicity.
+        This method is designed to be called periodically by the scheduler.
+        It is idempotent - safe to run multiple times without side effects.
+        """
+        db: Session = SessionLocal()
+
+        try:
+            self.logger.info("Starting auto-completion job for matches")
+
+            # Calculate the cutoff time (current time - 30 minutes)
+            now = datetime.now(timezone.utc)
+            cutoff_time = now - timedelta(minutes=30)
+
+            # Get the "completed" and "confirmed" status IDs
+            completed_status = db.query(MatchStatus).filter(MatchStatus.name == "completed").first()
+            confirmed_status = db.query(MatchStatus).filter(MatchStatus.name == "confirmed").first()
+
+            if not completed_status or not confirmed_status:
+                self.logger.error("Required match statuses not found in database")
+                return
+
+            # Build subquery to select qualifying time blocks once
+            timeblock_subquery = select(TimeBlock.id).where(TimeBlock.start_time < cutoff_time)
+
+            # Execute set-based UPDATE with returning clause so logging knows which rows changed
+            stmt = (
+                update(Match)
+                .where(
+                    Match.deleted_at.is_(None),
+                    Match.match_status_id == confirmed_status.id,
+                    Match.chosen_time_block_id.isnot(None),
+                    Match.chosen_time_block_id.in_(timeblock_subquery),
+                )
+                .values(match_status_id=completed_status.id, deleted_at=now)
+                .returning(Match.id, Match.participant_id, Match.volunteer_id)
+            )
+
+            result = db.execute(stmt)
+            db.commit()
+
+            completed_matches = result.fetchall()
+            if not completed_matches:
+                self.logger.info("No matches found that need auto-completion")
+                return
+
+            # Log each completed match for audit trail
+            for match in completed_matches:
+                self.logger.info(
+                    f"Auto-completed match {match.id} "
+                    f"(participant: {match.participant_id}, volunteer: {match.volunteer_id})"
+                )
+
+            self.logger.info(f"Successfully auto-completed {len(completed_matches)} match(es)")
+
+        except Exception as e:
+            db.rollback()
+            self.logger.error(f"Error in auto_complete_matches job: {str(e)}", exc_info=True)
+        finally:
+            db.close()

backend/pdm.lock

@@ -20,6 +20,7 @@ dependencies = [
     "boto3>=1.35.71",
     "pytest-asyncio>=0.25.3",
     "psycopg2-binary>=2.9.10",
+    "apscheduler>=3.10.4",
 ]
 requires-python = "==3.12.*"
 readme = "README.md"