Refactor backend: fix geo cache cleanup, scheduler heartbeat, correlation middleware; update docs

backend/app/main.py

@@ -254,8 +254,9 @@ async def _lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         # task's coroutine handles cleanup.
         import asyncio  # noqa: TC003
 
+        current_task = asyncio.current_task()
         pending_tasks: list[asyncio.Task[Any]] = [
-            t for t in asyncio.all_tasks() if not t.done()
+            t for t in asyncio.all_tasks() if not t.done() and t is not current_task
         ]
         if pending_tasks:
             log.info(

backend/app/startup.py

@@ -459,6 +459,8 @@ async def _stage_register_tasks(app: FastAPI, scheduler: AsyncIOScheduler) -> No
         app: The FastAPI application instance.
         scheduler: The APScheduler scheduler to register tasks with.
     """
+    # Set scheduler on app.state before registering tasks (they use app.state.scheduler)
+    app.state.scheduler = scheduler
     scheduler_lock_heartbeat.register(app)
     health_check.register(app)
     await blocklist_import.register(app)

backend/app/tasks/geo_cache_cleanup.py

@@ -114,7 +114,13 @@ def register(app: FastAPI) -> None:
             ``app.state.scheduler`` will receive the job.
     """
     settings = get_effective_settings(app)
-    app.state.scheduler.add_job(
+    scheduler = getattr(app.state, "scheduler", None)
+    if scheduler is None:
+        # In tests or standalone usage, scheduler may not be on app.state yet.
+        # Use a no-op fallback — the heartbeat won't be registered but no crash.
+        log.warning("geo_cache_cleanup_no_scheduler")
+        return
+    scheduler.add_job(
         _run_cleanup_with_resources,
         trigger="interval",
         seconds=GEO_CLEANUP_INTERVAL,

backend/app/tasks/scheduler_lock_heartbeat.py

@@ -121,7 +121,13 @@ def register(app: FastAPI) -> None:
             ``app.state.scheduler`` will receive the job.
     """
     settings = get_effective_settings(app)
-    app.state.scheduler.add_job(
+    scheduler = getattr(app.state, "scheduler", None)
+    if scheduler is None:
+        # In tests or standalone usage, scheduler may not be on app.state yet.
+        # Use a no-op fallback — the heartbeat won't be registered but no crash.
+        log.warning("scheduler_lock_heartbeat_no_scheduler")
+        return
+    scheduler.add_job(
         _update_heartbeat_with_resources,
         trigger="interval",
         seconds=SCHEDULER_LOCK_HEARTBEAT_INTERVAL,