feat(api): wire app assembly with lifespan, Sentry, and error tests [AYG-71]

Move Sentry SDK init into FastAPI lifespan startup (conditional on
SENTRY_DSN) so it activates after settings validation. Add structured
startup/shutdown log events with service_name, version, environment.
Flush Sentry on shutdown for graceful SIGTERM handling.

Remove broken legacy route imports from api/main.py (items, login,
private, users, utils) that reference deleted deps — entities is the
only active router. Rewrite conftest.py with modern test fixtures
using Supabase and Clerk dependency overrides against the real
assembled app. Legacy fixtures remain guarded for AYG-72 cleanup.

Add 7 integration tests verifying unified error response shape
(401/404/422/500), request_id propagation, security headers, and
X-Request-ID header across the full middleware + handler pipeline.

Fixes AYG-71
Related to AYG-64

🤖 Generated by Aygentic

Co-Authored-By: Aygentic <noreply@aygentic.com>

Author: amostt

backend/app/api/main.py

@@ -1,15 +1,6 @@
 from fastapi import APIRouter
 
-from app.api.routes import entities, items, login, private, users, utils
-from app.core.config import settings
+from app.api.routes import entities
 
 api_router = APIRouter()
-api_router.include_router(login.router)
-api_router.include_router(users.router)
-api_router.include_router(utils.router)
-api_router.include_router(items.router)
 api_router.include_router(entities.router)
-
-
-if settings.ENVIRONMENT == "local":
-    api_router.include_router(private.router)

backend/app/main.py

@@ -4,6 +4,8 @@
 import sentry_sdk
 from fastapi import FastAPI
 from fastapi.routing import APIRoute
+from sentry_sdk.integrations.fastapi import FastApiIntegration
+from sentry_sdk.integrations.starlette import StarletteIntegration
 from starlette.middleware.cors import CORSMiddleware
 
 from app.api.main import api_router
@@ -33,7 +35,24 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
         read_timeout=float(settings.HTTP_CLIENT_TIMEOUT),
         max_retries=settings.HTTP_CLIENT_MAX_RETRIES,
     )
-    logger.info("app_startup_complete")
+    if settings.SENTRY_DSN:
+        sentry_sdk.init(
+            dsn=str(settings.SENTRY_DSN),
+            integrations=[
+                StarletteIntegration(transaction_style="endpoint"),
+                FastApiIntegration(transaction_style="endpoint"),
+            ],
+            enable_tracing=True,
+            traces_sample_rate=0.1,
+            send_default_pii=False,
+            environment=settings.ENVIRONMENT,
+        )
+    logger.info(
+        "app_startup",
+        service_name=settings.SERVICE_NAME,
+        version=settings.SERVICE_VERSION,
+        environment=settings.ENVIRONMENT,
+    )
 
     yield
 
@@ -42,16 +61,19 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
         await app.state.http_client.close()
     except Exception:
         logger.exception("http_client_close_failed")
-    logger.info("app_shutdown_complete")
+    logger.info(
+        "app_shutdown",
+        service_name=settings.SERVICE_NAME,
+        version=settings.SERVICE_VERSION,
+        environment=settings.ENVIRONMENT,
+    )
+    sentry_sdk.flush(timeout=2.0)
 
 
 def custom_generate_unique_id(route: APIRoute) -> str:
     return f"{route.tags[0]}-{route.name}"
 
 
-if settings.SENTRY_DSN and settings.ENVIRONMENT != "local":
-    sentry_sdk.init(dsn=str(settings.SENTRY_DSN), enable_tracing=True)
-
 app = FastAPI(
     title=settings.SERVICE_NAME,
     openapi_url=f"{settings.API_V1_STR}/openapi.json",

backend/tests/conftest.py

@@ -1,27 +1,128 @@
+"""Shared pytest fixtures for the backend test suite.
+
+Modern fixtures (always available):
+  - mock_supabase           — MagicMock Supabase client (function-scoped)
+  - test_principal          — Principal with test user data (function-scoped)
+  - client                  — TestClient with Supabase + auth overrides (function-scoped)
+  - unauthenticated_client  — TestClient with only Supabase override (function-scoped)
+
+Legacy fixtures (guarded — remove in AYG-72):
+  - db, superuser_token_headers, normal_user_token_headers
+
+Env var defaults are set BEFORE any app imports to satisfy module-level
+Settings validation (SUPABASE_URL, SUPABASE_SERVICE_KEY, CLERK_SECRET_KEY).
+"""
+
+import os
 from collections.abc import Generator
+from unittest.mock import MagicMock
+
+# IMPORTANT: these defaults MUST be set before any `from app.*` imports.
+# app/core/config.py validates required settings at import time.
+os.environ.setdefault("SUPABASE_URL", "http://localhost:54321")
+os.environ.setdefault("SUPABASE_SERVICE_KEY", "test-service-key")
+os.environ.setdefault("CLERK_SECRET_KEY", "test-clerk-key")
 
 import pytest
+from fastapi.testclient import TestClient
+
+from app.core.auth import get_current_principal
+from app.core.supabase import get_supabase
+from app.main import app
+from app.models.auth import Principal
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+TEST_USER_ID = "user_test123"
+TEST_SESSION_ID = "sess_test"
+
+# ---------------------------------------------------------------------------
+# Modern fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def mock_supabase() -> MagicMock:
+    """Return a fresh MagicMock Supabase client for each test."""
+    return MagicMock()
+
+
+@pytest.fixture
+def test_principal() -> Principal:
+    """Return a Principal populated with deterministic test data."""
+    return Principal(
+        user_id=TEST_USER_ID,
+        session_id=TEST_SESSION_ID,
+        roles=[],
+        org_id=None,
+    )
+
+
+@pytest.fixture
+def client(
+    mock_supabase: MagicMock,
+    test_principal: Principal,
+) -> Generator[TestClient, None, None]:
+    """TestClient for the full app with Supabase and auth dependencies overridden.
 
-# Integration test fixtures require database and legacy settings that are being
-# migrated away (AYG-65 through AYG-74). Guard imports so unit tests can run
-# without --noconftest while integration fixtures are unavailable.
+    Both ``get_supabase`` and ``get_current_principal`` are replaced with
+    test doubles so no real database or Clerk credentials are required.
+
+    Dependency overrides are cleared on teardown to prevent state leakage
+    between tests that share the same ``app`` instance.
+    """
+    app.dependency_overrides[get_supabase] = lambda: mock_supabase
+    app.dependency_overrides[get_current_principal] = lambda: test_principal
+
+    with TestClient(app) as test_client:
+        yield test_client
+
+    app.dependency_overrides.clear()
+
+
+@pytest.fixture
+def unauthenticated_client(
+    mock_supabase: MagicMock,
+) -> Generator[TestClient, None, None]:
+    """TestClient with only the Supabase dependency overridden.
+
+    The real ``get_current_principal`` dependency runs, so any request to an
+    authenticated endpoint without a valid Clerk JWT will receive a 401 response.
+
+    Dependency overrides are cleared on teardown.
+    """
+    app.dependency_overrides[get_supabase] = lambda: mock_supabase
+
+    with TestClient(app, raise_server_exceptions=False) as test_client:
+        yield test_client
+
+    app.dependency_overrides.clear()
+
+
+# ---------------------------------------------------------------------------
+# Legacy fixtures (AYG-72: remove these once legacy test files are deleted)
+# ---------------------------------------------------------------------------
+
+# Integration test fixtures require legacy SQLAlchemy/DB dependencies that are
+# being migrated away (AYG-65 through AYG-74). Guard imports so unit tests and
+# modern integration tests can run even when legacy deps are missing.
 try:
-    from fastapi.testclient import TestClient
     from sqlmodel import Session, delete
 
     from app.core.config import settings
     from app.core.db import engine, init_db
-    from app.main import app
     from app.models import Item, User
     from tests.utils.user import authentication_token_from_email
     from tests.utils.utils import get_superuser_token_headers
 
-    _INTEGRATION_DEPS_AVAILABLE = True
-except (ImportError, AttributeError, Exception):
-    _INTEGRATION_DEPS_AVAILABLE = False
+    _LEGACY_DEPS_AVAILABLE = True
+except (ImportError, AttributeError):
+    _LEGACY_DEPS_AVAILABLE = False
 
 
-if _INTEGRATION_DEPS_AVAILABLE:
+if _LEGACY_DEPS_AVAILABLE:
 
     @pytest.fixture(scope="session", autouse=True)
     def db() -> Generator[Session, None, None]:  # type: ignore[type-arg]
@@ -34,11 +135,6 @@ def db() -> Generator[Session, None, None]:  # type: ignore[type-arg]
             session.execute(statement)
             session.commit()
 
-    @pytest.fixture(scope="module")
-    def client() -> Generator[TestClient, None, None]:
-        with TestClient(app) as c:
-            yield c
-
     @pytest.fixture(scope="module")
     def superuser_token_headers(client: TestClient) -> dict[str, str]:
         return get_superuser_token_headers(client)

backend/tests/integration/test_error_responses.py

@@ -0,0 +1,159 @@
+"""Integration tests for unified error response shape across the full app.
+
+Verifies that ALL error status codes (401, 404, 422, 500) return the unified
+JSON error shape when using the full assembled app. Tests the complete
+middleware + error handler pipeline end-to-end.
+
+Uses conftest.py fixtures:
+  - client                 — authenticated TestClient (Supabase + auth overridden)
+  - unauthenticated_client — TestClient with only Supabase overridden (401 on auth endpoints)
+  - mock_supabase          — MagicMock Supabase client (shared with client fixture)
+
+Run:
+  uv run pytest backend/tests/integration/test_error_responses.py -v
+"""
+
+import uuid
+from unittest.mock import MagicMock
+
+from fastapi.testclient import TestClient
+from postgrest.exceptions import APIError
+
+_PREFIX = "/api/v1"
+
+# ---------------------------------------------------------------------------
+# Security headers expected on every response
+# ---------------------------------------------------------------------------
+
+_EXPECTED_SECURITY_HEADERS: dict[str, str] = {
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "X-XSS-Protection": "0",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
+    "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+}
+
+
+# ---------------------------------------------------------------------------
+# TestUnifiedErrorShape — verifies shape for 401 / 404 / 422 / 500
+# ---------------------------------------------------------------------------
+
+
+class TestUnifiedErrorShape:
+    """Each error status code returns the unified JSON error shape."""
+
+    def test_401_returns_unified_error_shape(
+        self, unauthenticated_client: TestClient
+    ) -> None:
+        """Unauthenticated request returns 401 with unified error body."""
+        response = unauthenticated_client.get(f"{_PREFIX}/entities/")
+
+        assert response.status_code == 401
+        body = response.json()
+        assert "error" in body
+        assert "message" in body
+        assert "code" in body
+        assert "request_id" in body
+        assert body["error"] == "UNAUTHORIZED"
+
+    def test_404_returns_unified_error_shape(
+        self, client: TestClient, mock_supabase: MagicMock
+    ) -> None:
+        """Request for a non-existent entity returns 404 with ENTITY_NOT_FOUND."""
+        mock_supabase.table.return_value.select.return_value.eq.return_value.eq.return_value.single.return_value.execute.side_effect = APIError(
+            {"message": "No rows found", "code": "PGRST116"}
+        )
+
+        nonexistent_id = str(uuid.uuid4())
+        response = client.get(f"{_PREFIX}/entities/{nonexistent_id}")
+
+        assert response.status_code == 404
+        body = response.json()
+        assert "error" in body
+        assert "message" in body
+        assert "code" in body
+        assert "request_id" in body
+        assert body["error"] == "NOT_FOUND"
+        assert body["code"] == "ENTITY_NOT_FOUND"
+
+    def test_422_returns_unified_error_shape(self, client: TestClient) -> None:
+        """POST with missing required field returns 422 with details array."""
+        response = client.post(
+            f"{_PREFIX}/entities/",
+            json={"description": "no title"},
+        )
+
+        assert response.status_code == 422
+        body = response.json()
+        assert "error" in body
+        assert "message" in body
+        assert "code" in body
+        assert "request_id" in body
+        assert "details" in body
+        assert body["error"] == "VALIDATION_ERROR"
+        assert isinstance(body["details"], list)
+        assert len(body["details"]) >= 1
+        for detail in body["details"]:
+            assert "field" in detail
+            assert "message" in detail
+            assert "type" in detail
+
+    def test_500_returns_unified_error_shape(
+        self, client: TestClient, mock_supabase: MagicMock
+    ) -> None:
+        """Unhandled server exception returns 500 without leaking internal details."""
+        mock_supabase.table.side_effect = RuntimeError("db crash")
+
+        response = client.get(f"{_PREFIX}/entities/")
+
+        assert response.status_code == 500
+        body = response.json()
+        assert "error" in body
+        assert "message" in body
+        assert "code" in body
+        assert "request_id" in body
+        assert body["error"] == "INTERNAL_ERROR"
+        assert "db crash" not in body["message"]
+
+
+# ---------------------------------------------------------------------------
+# TestErrorResponseMetadata — request_id and security headers
+# ---------------------------------------------------------------------------
+
+
+class TestErrorResponseMetadata:
+    """Error responses include valid request_id and security headers."""
+
+    def test_error_response_includes_valid_request_id(
+        self, unauthenticated_client: TestClient
+    ) -> None:
+        """request_id in error body is a valid UUID string."""
+        response = unauthenticated_client.get(f"{_PREFIX}/entities/")
+
+        body = response.json()
+        assert "request_id" in body
+        # Raises ValueError if not a valid UUID — that is the assertion.
+        uuid.UUID(body["request_id"])
+
+    def test_error_response_has_security_headers(
+        self, unauthenticated_client: TestClient
+    ) -> None:
+        """All five security headers are present on error responses."""
+        response = unauthenticated_client.get(f"{_PREFIX}/entities/")
+
+        for header, expected_value in _EXPECTED_SECURITY_HEADERS.items():
+            assert header in response.headers, f"Missing security header: {header}"
+            assert response.headers[header] == expected_value, (
+                f"Header {header!r}: expected {expected_value!r}, "
+                f"got {response.headers[header]!r}"
+            )
+
+    def test_error_response_has_request_id_header(
+        self, unauthenticated_client: TestClient
+    ) -> None:
+        """X-Request-ID response header is present and is a valid UUID."""
+        response = unauthenticated_client.get(f"{_PREFIX}/entities/")
+
+        assert "X-Request-ID" in response.headers, "Missing X-Request-ID header"
+        # Raises ValueError if not a valid UUID — that is the assertion.
+        uuid.UUID(response.headers["X-Request-ID"])