feat(core): rewrite config, error handlers, and shared models [AYG-65] (#1)

* feat(core): rewrite config, error handlers, and shared models [AYG-65]

- Replace PostgreSQL/SMTP settings with Supabase+Clerk env vars
- Add frozen Settings with production secret and CORS guards
- Create unified error response shape with global exception handlers
- Add shared Pydantic models: ErrorResponse, ValidationErrorResponse, PaginatedResponse, Principal

Fixes AYG-65

🤖 Generated by Aygentic

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

* fix(core): untrack .env and guard conftest for migration [AYG-65]

- Remove .env from git tracking and add to .gitignore (SEC-001)
- Guard integration test conftest.py imports with try/except so unit
  tests run without --noconftest during the migration (FUNC-002)

Related to AYG-65

🤖 Generated by Aygentic

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

* fix(tests): harden test isolation for template usage [AYG-65]

- Catch all exceptions (including ValidationError) in conftest guard so
  pytest doesn't crash when env vars are unset in a fresh template clone
- Explicitly delenv missing vars in test_missing_required_var_raises so
  the test is deterministic regardless of the caller's shell environment

Related to AYG-65

🤖 Generated by Aygentic

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

* docs(project): update documentation before merge [skip ci]

Updated documentation based on AYG-65 code changes:
- setup.md: replaced PostgreSQL/SMTP/JWT env vars with Supabase/Clerk
- deployment/environments.md: updated all env tables and GitHub Secrets
- architecture/overview.md: added error handling framework, shared models, Clerk auth
- architecture/decisions/: new ADRs for error handling and models package
- api/overview.md: Clerk auth, standard error shape, paginated response pattern
- api/endpoints/login.md: deprecated (Clerk migration)
- api/endpoints/users.md + items.md: updated auth and error response docs
- data/models.md: new Shared Pydantic Models section
- testing/test-registry.md: +36 unit tests, closed config coverage gap

Related to AYG-65

🤖 Generated by Aygentic

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

---------

Co-authored-by: Aygentic <noreply@aygentic.com>

Author: amostt

.env

@@ -1,3 +1,6 @@
+.env
+.env.*
+!.env.example
 .vscode/*
 !.vscode/extensions.json
 node_modules/

.gitignore

@@ -1,101 +1,67 @@
-import secrets
+import json
 import warnings
 from typing import Annotated, Any, Literal
 
-from pydantic import (
-    AnyUrl,
-    BeforeValidator,
-    EmailStr,
-    HttpUrl,
-    PostgresDsn,
-    computed_field,
-    model_validator,
-)
+from pydantic import AnyUrl, BeforeValidator, SecretStr, computed_field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from typing_extensions import Self
 
 
 def parse_cors(v: Any) -> list[str] | str:
-    if isinstance(v, str) and not v.startswith("["):
+    if isinstance(v, str) and v.startswith("["):
+        return json.loads(v)
+    if isinstance(v, str):
         return [i.strip() for i in v.split(",") if i.strip()]
-    elif isinstance(v, list | str):
+    elif isinstance(v, list):
         return v
     raise ValueError(v)
 
 
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(
-        # Use top level .env file (one level above ./backend/)
         env_file="../.env",
         env_ignore_empty=True,
         extra="ignore",
+        frozen=True,
     )
-    API_V1_STR: str = "/api/v1"
-    SECRET_KEY: str = secrets.token_urlsafe(32)
-    # 60 minutes * 24 hours * 8 days = 8 days
-    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24 * 8
-    FRONTEND_HOST: str = "http://localhost:5173"
-    ENVIRONMENT: Literal["local", "staging", "production"] = "local"
-
-    BACKEND_CORS_ORIGINS: Annotated[
-        list[AnyUrl] | str, BeforeValidator(parse_cors)
-    ] = []
-
-    @computed_field  # type: ignore[prop-decorator]
-    @property
-    def all_cors_origins(self) -> list[str]:
-        return [str(origin).rstrip("/") for origin in self.BACKEND_CORS_ORIGINS] + [
-            self.FRONTEND_HOST
-        ]
-
-    PROJECT_NAME: str
-    SENTRY_DSN: HttpUrl | None = None
-    POSTGRES_SERVER: str
-    POSTGRES_PORT: int = 5432
-    POSTGRES_USER: str
-    POSTGRES_PASSWORD: str = ""
-    POSTGRES_DB: str = ""
-
-    @computed_field  # type: ignore[prop-decorator]
-    @property
-    def SQLALCHEMY_DATABASE_URI(self) -> PostgresDsn:
-        return PostgresDsn.build(
-            scheme="postgresql+psycopg",
-            username=self.POSTGRES_USER,
-            password=self.POSTGRES_PASSWORD,
-            host=self.POSTGRES_SERVER,
-            port=self.POSTGRES_PORT,
-            path=self.POSTGRES_DB,
-        )
 
-    SMTP_TLS: bool = True
-    SMTP_SSL: bool = False
-    SMTP_PORT: int = 587
-    SMTP_HOST: str | None = None
-    SMTP_USER: str | None = None
-    SMTP_PASSWORD: str | None = None
-    EMAILS_FROM_EMAIL: EmailStr | None = None
-    EMAILS_FROM_NAME: str | None = None
+    # Required fields — no defaults; must come from environment
+    SUPABASE_URL: AnyUrl
+    SUPABASE_SERVICE_KEY: SecretStr
+    CLERK_SECRET_KEY: SecretStr
 
-    @model_validator(mode="after")
-    def _set_default_emails_from(self) -> Self:
-        if not self.EMAILS_FROM_NAME:
-            self.EMAILS_FROM_NAME = self.PROJECT_NAME
-        return self
-
-    EMAIL_RESET_TOKEN_EXPIRE_HOURS: int = 48
+    # Optional fields with defaults
+    ENVIRONMENT: Literal["local", "staging", "production"] = "local"
+    SERVICE_NAME: str = "my-service"
+    SERVICE_VERSION: str = "0.1.0"
+    LOG_LEVEL: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+    LOG_FORMAT: Literal["json", "console"] = "json"
+    API_V1_STR: str = "/api/v1"
+    BACKEND_CORS_ORIGINS: Annotated[list[str] | str, BeforeValidator(parse_cors)] = []
+    WITH_UI: bool = False
+    CLERK_JWKS_URL: str | None = None
+    CLERK_AUTHORIZED_PARTIES: list[str] = []
+    GIT_COMMIT: str = "unknown"
+    BUILD_TIME: str = "unknown"
+    HTTP_CLIENT_TIMEOUT: int = 30
+    HTTP_CLIENT_MAX_RETRIES: int = 3
+    SENTRY_DSN: str | None = None
 
     @computed_field  # type: ignore[prop-decorator]
     @property
-    def emails_enabled(self) -> bool:
-        return bool(self.SMTP_HOST and self.EMAILS_FROM_EMAIL)
-
-    EMAIL_TEST_USER: EmailStr = "test@example.com"
-    FIRST_SUPERUSER: EmailStr
-    FIRST_SUPERUSER_PASSWORD: str
-
-    def _check_default_secret(self, var_name: str, value: str | None) -> None:
-        if value == "changethis":
+    def all_cors_origins(self) -> list[str]:
+        return [str(origin).rstrip("/") for origin in self.BACKEND_CORS_ORIGINS]
+
+    def _check_default_secret(
+        self, var_name: str, value: str | SecretStr | None
+    ) -> None:
+        secret_value: str | None
+        if isinstance(value, SecretStr):
+            secret_value = value.get_secret_value()
+        else:
+            secret_value = value
+
+        if secret_value == "changethis":
             message = (
                 f'The value of {var_name} is "changethis", '
                 "for security, please change it, at least for deployments."
@@ -107,11 +73,19 @@ def _check_default_secret(self, var_name: str, value: str | None) -> None:
 
     @model_validator(mode="after")
     def _enforce_non_default_secrets(self) -> Self:
-        self._check_default_secret("SECRET_KEY", self.SECRET_KEY)
-        self._check_default_secret("POSTGRES_PASSWORD", self.POSTGRES_PASSWORD)
-        self._check_default_secret(
-            "FIRST_SUPERUSER_PASSWORD", self.FIRST_SUPERUSER_PASSWORD
-        )
+        self._check_default_secret("SUPABASE_SERVICE_KEY", self.SUPABASE_SERVICE_KEY)
+        self._check_default_secret("CLERK_SECRET_KEY", self.CLERK_SECRET_KEY)
+
+        if self.ENVIRONMENT == "production":
+            cors_list = self.BACKEND_CORS_ORIGINS
+            if isinstance(cors_list, str):
+                origins = [cors_list]
+            else:
+                origins = [str(o) for o in cors_list]
+            if "*" in origins:
+                raise ValueError(
+                    "wildcard CORS origin ('*') is not allowed in production"
+                )
 
         return self
 

backend/app/core/config.py

@@ -0,0 +1,142 @@
+"""Unified error handling framework.
+
+Provides ServiceError exception, HTTP status code mapping, and global
+exception handlers that format all API errors into a standard JSON shape.
+"""
+
+import logging
+from uuid import uuid4
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from app.models.common import (
+    ErrorResponse,
+    ValidationErrorDetail,
+    ValidationErrorResponse,
+)
+
+logger = logging.getLogger(__name__)
+
+# HTTP status code → error category mapping
+STATUS_CODE_MAP: dict[int, str] = {
+    400: "BAD_REQUEST",
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    409: "CONFLICT",
+    422: "VALIDATION_ERROR",
+    429: "RATE_LIMITED",
+    500: "INTERNAL_ERROR",
+    503: "SERVICE_UNAVAILABLE",
+}
+
+
+class ServiceError(Exception):
+    """Application-level error with structured error info.
+
+    Usage::
+
+        raise ServiceError(
+            status_code=404,
+            message="Entity not found",
+            code="ENTITY_NOT_FOUND",
+        )
+    """
+
+    def __init__(self, status_code: int, message: str, code: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.code = code
+        self.error = STATUS_CODE_MAP.get(status_code, "INTERNAL_ERROR")
+        super().__init__(message)
+
+
+def _get_request_id(request: Request) -> str:
+    """Extract request_id from request state, or generate a new UUID."""
+    return getattr(request.state, "request_id", None) or str(uuid4())
+
+
+async def service_error_handler(request: Request, exc: ServiceError) -> JSONResponse:
+    """Handle ServiceError exceptions."""
+    request_id = _get_request_id(request)
+    body = ErrorResponse(
+        error=exc.error,
+        message=exc.message,
+        code=exc.code,
+        request_id=request_id,
+    )
+    return JSONResponse(status_code=exc.status_code, content=body.model_dump())
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    """Handle FastAPI/Starlette HTTPException."""
+    request_id = _get_request_id(request)
+    error = STATUS_CODE_MAP.get(exc.status_code, "INTERNAL_ERROR")
+    message = str(exc.detail) if exc.detail else error
+    body = ErrorResponse(
+        error=error,
+        message=message,
+        code=error,
+        request_id=request_id,
+    )
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=body.model_dump(),
+        headers=getattr(exc, "headers", None),
+    )
+
+
+async def validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    """Handle Pydantic RequestValidationError with field-level details."""
+    request_id = _get_request_id(request)
+    details = []
+    for err in exc.errors():
+        # Convert loc tuple to dot-notation field path.
+        # loc is like ("body", "title") or ("query", "page").
+        # Skip the first element if it's a location prefix.
+        loc_parts = [str(part) for part in err.get("loc", [])]
+        if loc_parts and loc_parts[0] in ("body", "query", "path", "header", "cookie"):
+            loc_parts = loc_parts[1:]
+        field = ".".join(loc_parts) if loc_parts else "unknown"
+        details.append(
+            ValidationErrorDetail(
+                field=field,
+                message=err.get("msg", "Validation error"),
+                type=err.get("type", "value_error"),
+            )
+        )
+    body = ValidationErrorResponse(
+        error="VALIDATION_ERROR",
+        message="Request validation failed.",
+        code="VALIDATION_FAILED",
+        request_id=request_id,
+        details=details,
+    )
+    return JSONResponse(status_code=422, content=body.model_dump())
+
+
+async def unhandled_exception_handler(
+    request: Request, exc: Exception
+) -> JSONResponse:
+    """Catch-all handler for unhandled exceptions."""
+    request_id = _get_request_id(request)
+    logger.exception("Unhandled exception [request_id=%s]", request_id, exc_info=exc)
+    body = ErrorResponse(
+        error="INTERNAL_ERROR",
+        message="An unexpected error occurred.",
+        code="INTERNAL_ERROR",
+        request_id=request_id,
+    )
+    return JSONResponse(status_code=500, content=body.model_dump())
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """Register all global exception handlers on the FastAPI app."""
+    app.add_exception_handler(ServiceError, service_error_handler)  # type: ignore[arg-type]
+    app.add_exception_handler(HTTPException, http_exception_handler)  # type: ignore[arg-type]
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)  # type: ignore[arg-type]
+    app.add_exception_handler(Exception, unhandled_exception_handler)

backend/app/core/errors.py

@@ -5,6 +5,7 @@
 
 from app.api.main import api_router
 from app.core.config import settings
+from app.core.errors import register_exception_handlers
 
 
 def custom_generate_unique_id(route: APIRoute) -> str:
@@ -15,11 +16,14 @@ def custom_generate_unique_id(route: APIRoute) -> str:
     sentry_sdk.init(dsn=str(settings.SENTRY_DSN), enable_tracing=True)
 
 app = FastAPI(
-    title=settings.PROJECT_NAME,
+    title=settings.SERVICE_NAME,
     openapi_url=f"{settings.API_V1_STR}/openapi.json",
     generate_unique_id_function=custom_generate_unique_id,
 )
 
+# Register unified error handlers
+register_exception_handlers(app)
+
 # Set all CORS enabled origins
 if settings.all_cors_origins:
     app.add_middleware(