Optimize dashboard overview loading

api/routers/workstreams.py

@@ -3,6 +3,7 @@ import logging
 import uuid
 import socket
 import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
@@ -40,6 +41,8 @@ workplan_router = APIRouter(prefix="/workplans", tags=["workplans"])
 _INDEX_CACHE: dict[str, Any] | None = None
 _INDEX_CACHE_AT: float = 0.0
 _INDEX_TTL = 30.0
+_INDEX_REFRESH_TASK: asyncio.Task | None = None
+_INDEX_LAST_ERROR: str | None = None
 
 _LEGACY_OWNER = "state-hub.api"
 _COMPLETED_WORKSTREAM_EVENT = "org.statehub.workstream.completed"
@@ -170,16 +173,7 @@ async def _list_workstreams(
     return list(result.scalars().all())
 
 
-async def _workplan_index(
-    *,
-    refresh: bool,
-    session: AsyncSession,
-) -> dict[str, Any]:
-    """Map file-backed workplan ids to their local workplan filenames."""
-    global _INDEX_CACHE, _INDEX_CACHE_AT
-    if not refresh and _INDEX_CACHE is not None and (time.monotonic() - _INDEX_CACHE_AT) < _INDEX_TTL:
-        return _INDEX_CACHE
-
+async def _build_workplan_index(session: AsyncSession) -> dict[str, Any]:
     result = await session.execute(
         select(ManagedRepo).where(ManagedRepo.status == "active").order_by(ManagedRepo.slug)
     )
@@ -218,8 +212,78 @@ async def _workplan_index(
                     "needs_review": bool(review and review.needs_review),
                     "health_labels": ["needs_review"] if review and review.needs_review else [],
                 }
-    _INDEX_CACHE = {"workplans": index, "workstreams": index}
+    return {"workplans": index, "workstreams": index}
+
+
+def _index_with_meta(*, stale: bool, refresh_in_progress: bool) -> dict[str, Any]:
+    age = time.monotonic() - _INDEX_CACHE_AT if _INDEX_CACHE_AT else None
+    return {
+        **(_INDEX_CACHE or {"workplans": {}, "workstreams": {}}),
+        "_meta": {
+            "generated_at": _INDEX_CACHE.get("_meta", {}).get("generated_at") if _INDEX_CACHE else None,
+            "stale": stale,
+            "cache_age_seconds": round(age, 3) if age is not None else None,
+            "refresh_in_progress": refresh_in_progress,
+            "last_error": _INDEX_LAST_ERROR,
+        },
+    }
+
+
+async def _refresh_workplan_index_background() -> None:
+    global _INDEX_CACHE, _INDEX_CACHE_AT, _INDEX_LAST_ERROR
+    from api.database import async_session_factory
+
+    try:
+        async with async_session_factory() as session:
+            index = await _build_workplan_index(session)
+        index["_meta"] = {
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "stale": False,
+            "cache_age_seconds": 0.0,
+            "refresh_in_progress": False,
+            "last_error": None,
+        }
+        _INDEX_CACHE = index
+        _INDEX_CACHE_AT = time.monotonic()
+        _INDEX_LAST_ERROR = None
+    except Exception as exc:
+        _INDEX_LAST_ERROR = str(exc)
+
+
+def _ensure_index_refresh_started() -> None:
+    global _INDEX_REFRESH_TASK
+    if _INDEX_REFRESH_TASK is not None and not _INDEX_REFRESH_TASK.done():
+        return
+    _INDEX_REFRESH_TASK = asyncio.create_task(_refresh_workplan_index_background())
+
+
+async def _workplan_index(
+    *,
+    refresh: bool,
+    session: AsyncSession,
+) -> dict[str, Any]:
+    """Map file-backed workplan ids to their local workplan filenames."""
+    global _INDEX_CACHE, _INDEX_CACHE_AT, _INDEX_LAST_ERROR
+    cache_age = time.monotonic() - _INDEX_CACHE_AT if _INDEX_CACHE_AT else None
+    if not refresh and _INDEX_CACHE is not None and cache_age is not None and cache_age < _INDEX_TTL:
+        refresh_running = _INDEX_REFRESH_TASK is not None and not _INDEX_REFRESH_TASK.done()
+        return _index_with_meta(stale=False, refresh_in_progress=refresh_running)
+
+    if not refresh and _INDEX_CACHE is not None:
+        _ensure_index_refresh_started()
+        return _index_with_meta(stale=True, refresh_in_progress=True)
+
+    index = await _build_workplan_index(session)
+    index["_meta"] = {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "stale": False,
+        "cache_age_seconds": 0.0,
+        "refresh_in_progress": False,
+        "last_error": None,
+    }
+    _INDEX_CACHE = index
     _INDEX_CACHE_AT = time.monotonic()
+    _INDEX_LAST_ERROR = None
     return _INDEX_CACHE