fix(api): degrade gracefully when graph is unavailable

src/civicsetu/api/main.py

@@ -123,6 +123,13 @@ def create_app() -> FastAPI:
     app.include_router(query.router, prefix="/api/v1", tags=["query"])
     app.include_router(graph.router, prefix="/api/v1", tags=["graph"])
 
+    @app.get("/")
+    async def root():
+        return {
+            "message": "CivicSetu API is running. Frontend is served separately in this deployment.",
+            "status": "ok",
+        }
+
     return app
 
 app = create_app()

src/civicsetu/api/routes/graph.py

@@ -31,6 +31,18 @@ router = APIRouter()
 
 _topo_cache: dict = {"data": None, "ts": 0.0}
 _TOPO_TTL = 300
+_EMPTY_GRAPH_STATS = {
+    "docs": 0,
+    "sections": 0,
+    "refs": 0,
+    "has_sec": 0,
+    "derived_from": 0,
+}
+
+
+def _is_neo4j_auth_error(error: Exception) -> bool:
+    message = str(error)
+    return "Neo.ClientError.Security.Unauthorized" in message or "authentication failure" in message
 
 
 @router.get("/graph/topology", response_model=GraphTopologyResponse)
@@ -45,6 +57,12 @@ async def get_graph_topology() -> GraphTopologyResponse:
         nodes_raw, edges_raw = await GraphStore.get_topology()
         stats = await GraphStore.graph_stats()
     except Exception as e:
+        if _is_neo4j_auth_error(e):
+            log.warning("topology_fetch_degraded", reason="neo4j_auth_failed")
+            response = GraphTopologyResponse(nodes=[], edges=[], stats=_EMPTY_GRAPH_STATS)
+            _topo_cache["data"] = response
+            _topo_cache["ts"] = now
+            return response
         log.error("topology_fetch_failed", error=str(e))
         raise HTTPException(status_code=500, detail=f"Graph topology fetch failed: {e}")
 

tests/unit/api/test_query_route.py

@@ -105,6 +105,41 @@ def test_app_startup_on_non_windows_does_not_shadow_asyncio():
     mock_get_ranker.assert_called_once()
 
 
+def test_root_returns_ok_when_frontend_not_served(client):
+    test_client, _ = client
+
+    response = test_client.get("/")
+
+    assert response.status_code == 200
+    assert response.json()["status"] == "ok"
+
+
+def test_graph_topology_returns_empty_payload_when_neo4j_auth_fails(client):
+    test_client, _ = client
+
+    with patch(
+        "civicsetu.api.routes.graph.GraphStore.get_topology",
+        new=AsyncMock(side_effect=RuntimeError("Neo.ClientError.Security.Unauthorized")),
+    ), patch(
+        "civicsetu.api.routes.graph.GraphStore.graph_stats",
+        new=AsyncMock(side_effect=RuntimeError("Neo.ClientError.Security.Unauthorized")),
+    ):
+        response = test_client.get("/api/v1/graph/topology")
+
+    assert response.status_code == 200
+    assert response.json() == {
+        "nodes": [],
+        "edges": [],
+        "stats": {
+            "docs": 0,
+            "sections": 0,
+            "refs": 0,
+            "has_sec": 0,
+            "derived_from": 0,
+        },
+    }
+
+
 def test_query_returns_200_with_citations(client):
     test_client, mock_graph = client
     mock_graph.invoke.return_value = {