fix(api): mount Next.js frontend as default app and prefix all API routes under /api

synthra/api/app.py

@@ -2,9 +2,11 @@ import os
 import logging
 import time
 from contextlib import asynccontextmanager
-from typing import AsyncGenerator
-from fastapi import FastAPI
+from typing import Any, AsyncGenerator
+from fastapi import FastAPI, HTTPException
 from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from synthra.api.routers import health, status, campaigns, auth
 from synthra.api.state import ServiceState
@@ -14,6 +16,28 @@ logger = logging.getLogger(__name__)
 _START_TIME: float = 0.0
 
 
+class SPAStaticFiles(StaticFiles):
+    """Custom StaticFiles subclass supporting SPA routing fallback to index.html."""
+
+    async def get_response(self, path: str, scope: Any) -> Any:
+        # Check if the path is an API path (normalizing path separators for cross-platform compatibility)
+        clean_path = path.replace("\\", "/").lstrip("/")
+        if clean_path.startswith("api/") or clean_path == "api":
+            raise HTTPException(status_code=404, detail="Not Found")
+
+        try:
+            response = await super().get_response(path, scope)
+            if response.status_code == 404:
+                return FileResponse(os.path.join(self.directory, "index.html"))
+            return response
+        except (HTTPException, StarletteHTTPException) as ex:
+            if ex.status_code == 404:
+                return FileResponse(os.path.join(self.directory, "index.html"))
+            raise ex
+        except Exception:
+            return FileResponse(os.path.join(self.directory, "index.html"))
+
+
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     """Handle startup and shutdown lifecycle events."""
@@ -47,12 +71,6 @@ def create_app() -> FastAPI:
         redoc_url="/redoc",
     )
 
-    # Root-level router registration (backward compatibility for existing tests)
-    application.include_router(health.router)
-    application.include_router(status.router)
-    application.include_router(campaigns.router)
-    application.include_router(auth.router)
-
     # Prefix-level router registration (production frontend)
     application.include_router(health.router, prefix="/api")
     application.include_router(status.router, prefix="/api")
@@ -68,15 +86,6 @@ def create_app() -> FastAPI:
             "status": "running",
         }
 
-    @application.get("/", tags=["root"])
-    async def root() -> dict[str, str]:
-        """Root endpoint returning service identity."""
-        return {
-            "service": "Synthra",
-            "version": "0.1.0",
-            "status": "running",
-        }
-
     # Mount Next.js static exported HTML
     root_dir = os.path.dirname(
         os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
@@ -84,7 +93,7 @@ def create_app() -> FastAPI:
     frontend_out = os.path.join(root_dir, "frontend", "out")
     if os.path.exists(frontend_out):
         application.mount(
-            "/", StaticFiles(directory=frontend_out, html=True), name="static"
+            "/", SPAStaticFiles(directory=frontend_out, html=True), name="static"
         )
 
     return application

tests/api/test_app.py

@@ -47,8 +47,8 @@ def client() -> Generator[TestClient, None, None]:
 
 
 def test_root_returns_service_identity(client: TestClient) -> None:
-    """GET / returns service name, version, and running status."""
-    response = client.get("/")
+    """GET /api returns service name, version, and running status."""
+    response = client.get("/api")
     assert response.status_code == 200
     body = response.json()
     assert body["service"] == "Synthra"
@@ -62,18 +62,18 @@ def test_root_returns_service_identity(client: TestClient) -> None:
 
 
 def test_health_returns_healthy(client: TestClient) -> None:
-    """GET /health returns status=healthy."""
-    response = client.get("/health")
+    """GET /api/health returns status=healthy."""
+    response = client.get("/api/health")
     assert response.status_code == 200
     assert response.json() == {"status": "healthy"}
 
 
 def test_health_is_fast(client: TestClient) -> None:
-    """GET /health must complete without touching state or DB."""
+    """GET /api/health must complete without touching state or DB."""
     import time
 
     start = time.perf_counter()
-    response = client.get("/health")
+    response = client.get("/api/health")
     elapsed = time.perf_counter() - start
 
     assert response.status_code == 200
@@ -87,8 +87,8 @@ def test_health_is_fast(client: TestClient) -> None:
 
 
 def test_status_returns_expected_schema(client: TestClient) -> None:
-    """GET /status returns version, uptime_seconds, and memory sub-object."""
-    response = client.get("/status")
+    """GET /api/status returns version, uptime_seconds, and memory sub-object."""
+    response = client.get("/api/status")
     assert response.status_code == 200
     body = response.json()
 
@@ -108,8 +108,8 @@ def test_status_returns_expected_schema(client: TestClient) -> None:
 
 
 def test_campaigns_list_returns_empty(client: TestClient) -> None:
-    """GET /campaigns returns empty list and zero total."""
-    response = client.get("/campaigns")
+    """GET /api/campaigns returns empty list and total."""
+    response = client.get("/api/campaigns")
     assert response.status_code == 200
     body = response.json()
     assert body["campaigns"] == []
@@ -136,12 +136,12 @@ def test_state_module_importable() -> None:
 
 
 def test_run_campaign_endpoint(client: TestClient) -> None:
-    """POST /campaigns/{campaign_id}/run calls governor.run_campaign."""
+    """POST /api/campaigns/{campaign_id}/run calls governor.run_campaign."""
     from synthra.api.app import ServiceState
 
     mock_state = ServiceState.get_instance()
 
-    response = client.post("/campaigns/CMP-0001/run")
+    response = client.post("/api/campaigns/CMP-0001/run")
     assert response.status_code == 200
     assert response.json() == {
         "status": "success",
@@ -151,13 +151,13 @@ def test_run_campaign_endpoint(client: TestClient) -> None:
 
 
 def test_run_campaign_endpoint_error(client: TestClient) -> None:
-    """POST /campaigns/{campaign_id}/run handles errors properly."""
+    """POST /api/campaigns/{campaign_id}/run handles errors properly."""
     from synthra.api.app import ServiceState
 
     mock_state = ServiceState.get_instance()
     mock_state.governor.run_campaign.side_effect = ValueError("Some campaign error")
 
-    response = client.post("/campaigns/CMP-0001/run")
+    response = client.post("/api/campaigns/CMP-0001/run")
     assert response.status_code == 200
     assert response.json() == {
         "status": "error",

tests/api/test_auth.py

@@ -43,11 +43,11 @@ def client(mock_service_state):
 
 
 def test_login_success(client, mock_service_state):
-    """POST /auth/login returns success on valid credentials."""
+    """POST /api/auth/login returns success on valid credentials."""
     mock_service_state.execution_client.authenticate.return_value = None
 
     response = client.post(
-        "/auth/login",
+        "/api/auth/login",
         json={"username": "test_user", "password": "test_password", "remember": True},
     )
     assert response.status_code == 200
@@ -64,13 +64,13 @@ def test_login_success(client, mock_service_state):
 
 
 def test_login_invalid_credentials(client, mock_service_state):
-    """POST /auth/login returns error on invalid credentials."""
+    """POST /api/auth/login returns error on invalid credentials."""
     mock_service_state.execution_client.authenticate.side_effect = (
         ExecutionAuthenticationError("Auth failed")
     )
 
     response = client.post(
-        "/auth/login",
+        "/api/auth/login",
         json={"username": "bad_user", "password": "bad_password", "remember": False},
     )
     assert response.status_code == 200
@@ -84,13 +84,13 @@ def test_login_invalid_credentials(client, mock_service_state):
 
 
 def test_login_verification_required(client, mock_service_state):
-    """POST /auth/login returns verification_required status on MFA."""
+    """POST /api/auth/login returns verification_required status on MFA."""
     mock_service_state.execution_client.authenticate.side_effect = (
         VerificationRequiredError("https://mfa.example.test")
     )
 
     response = client.post(
-        "/auth/login",
+        "/api/auth/login",
         json={"username": "mfa_user", "password": "mfa_password", "remember": False},
     )
     assert response.status_code == 200
@@ -105,8 +105,8 @@ def test_login_verification_required(client, mock_service_state):
 
 
 def test_status_unauthenticated(client):
-    """GET /auth/status returns unauthenticated when no session exists."""
-    response = client.get("/auth/status")
+    """GET /api/auth/status returns unauthenticated when no session exists."""
+    response = client.get("/api/auth/status")
     assert response.status_code == 200
     assert response.json() == {
         "authenticated": False,
@@ -117,18 +117,18 @@ def test_status_unauthenticated(client):
 
 
 def test_status_authenticated_and_logout(client, mock_service_state):
-    """GET /auth/status returns authenticated and POST /auth/logout clears session."""
+    """GET /api/auth/status returns authenticated and logout clears session."""
     mock_service_state.execution_client.authenticate.return_value = None
 
     # 1. Login to establish session
     login_resp = client.post(
-        "/auth/login",
+        "/api/auth/login",
         json={"username": "user1", "password": "pass1", "remember": False},
     )
     assert login_resp.status_code == 200
 
     # 2. Get status with cookie
-    status_resp = client.get("/auth/status")
+    status_resp = client.get("/api/auth/status")
     assert status_resp.status_code == 200
     assert status_resp.json() == {
         "authenticated": True,
@@ -138,12 +138,12 @@ def test_status_authenticated_and_logout(client, mock_service_state):
     }
 
     # 3. Invalidate via logout
-    logout_resp = client.post("/auth/logout")
+    logout_resp = client.post("/api/auth/logout")
     assert logout_resp.status_code == 200
     assert logout_resp.json() == {"status": "success", "message": None}
 
     # Cookie should be deleted
     # 4. Status should now be unauthenticated
-    status_resp_after = client.get("/auth/status")
+    status_resp_after = client.get("/api/auth/status")
     assert status_resp_after.status_code == 200
     assert status_resp_after.json()["authenticated"] is False

tests/api/test_telemetry_endpoints.py

@@ -112,8 +112,8 @@ def client() -> Generator[TestClient, None, None]:
 
 
 def test_get_metrics(client: TestClient) -> None:
-    """GET /metrics returns the telemetry metrics."""
-    response = client.get("/metrics")
+    """GET /api/metrics returns the telemetry metrics."""
+    response = client.get("/api/metrics")
     assert response.status_code == 200
     metrics = response.json()
     assert metrics["running_workers"] == 2
@@ -122,8 +122,8 @@ def test_get_metrics(client: TestClient) -> None:
 
 
 def test_get_workers(client: TestClient) -> None:
-    """GET /workers returns the status of active worker threads."""
-    response = client.get("/workers")
+    """GET /api/workers returns the status of active worker threads."""
+    response = client.get("/api/workers")
     assert response.status_code == 200
     workers = response.json()
     assert len(workers) == 2
@@ -134,8 +134,8 @@ def test_get_workers(client: TestClient) -> None:
 
 
 def test_get_campaigns(client: TestClient) -> None:
-    """GET /campaigns returns the list of all campaigns with state."""
-    response = client.get("/campaigns")
+    """GET /api/campaigns returns the list of all campaigns with state."""
+    response = client.get("/api/campaigns")
     assert response.status_code == 200
     body = response.json()
     assert body["total"] == 1
@@ -145,8 +145,8 @@ def test_get_campaigns(client: TestClient) -> None:
 
 
 def test_get_queue(client: TestClient) -> None:
-    """GET /queue returns campaigns currently in the queue."""
-    response = client.get("/queue")
+    """GET /api/queue returns campaigns currently in the queue."""
+    response = client.get("/api/queue")
     assert response.status_code == 200
     queue = response.json()
     assert len(queue) == 1
@@ -155,8 +155,8 @@ def test_get_queue(client: TestClient) -> None:
 
 
 def test_get_candidates(client: TestClient) -> None:
-    """GET /candidates returns alpha candidates enqueued for submission."""
-    response = client.get("/candidates")
+    """GET /api/candidates returns alpha candidates enqueued for submission."""
+    response = client.get("/api/candidates")
     assert response.status_code == 200
     candidates = response.json()
     assert len(candidates) == 1
@@ -165,8 +165,8 @@ def test_get_candidates(client: TestClient) -> None:
 
 
 def test_get_events(client: TestClient) -> None:
-    """GET /events returns recent events."""
-    response = client.get("/events")
+    """GET /api/events returns recent events."""
+    response = client.get("/api/events")
     assert response.status_code == 200
     events = response.json()
     assert len(events) == 1
@@ -175,8 +175,8 @@ def test_get_events(client: TestClient) -> None:
 
 
 def test_get_system(client: TestClient) -> None:
-    """GET /system returns system stats."""
-    response = client.get("/system")
+    """GET /api/system returns system stats."""
+    response = client.get("/api/system")
     assert response.status_code == 200
     system = response.json()
     assert system["database_backend"] == "sqlite"
@@ -185,8 +185,8 @@ def test_get_system(client: TestClient) -> None:
 
 
 def test_get_governor(client: TestClient) -> None:
-    """GET /governor returns governor stats and configuration."""
-    response = client.get("/governor")
+    """GET /api/governor returns governor stats and configuration."""
+    response = client.get("/api/governor")
     assert response.status_code == 200
     governor = response.json()
     assert governor["status"] == "running"
@@ -195,7 +195,7 @@ def test_get_governor(client: TestClient) -> None:
 
 
 def test_events_stream(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
-    """GET /events/stream returns event-stream media type."""
+    """GET /api/events/stream returns event-stream media type."""
     from typing import Any, AsyncGenerator
     from fastapi import Request
 
@@ -206,6 +206,6 @@ def test_events_stream(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> N
 
     monkeypatch.setattr("synthra.api.routers.status.sse_generator", mock_sse_generator)
 
-    with client.stream("GET", "/events/stream") as response:
+    with client.stream("GET", "/api/events/stream") as response:
         assert response.status_code == 200
         assert "text/event-stream" in response.headers["content-type"]