Introduce domain exception hierarchy for transport-agnostic services

  - Add base exceptions in app/domain/exceptions.py (NotFoundError,
    ValidationError, ThrottledError, ConflictError, UnauthorizedError,
    ForbiddenError, InvalidStateError, InfrastructureError)
  - Create domain-specific exceptions for execution, saga, notification,
    saved_script, replay, and user/auth modules
  - Update all services to throw domain exceptions instead of HTTPException
  - Add single exception handler middleware that maps to HTTP status codes
  - Add documentation in docs/architecture/domain-exceptions.md

  Services no longer know about HTTP semantics. The middleware handles
  all mapping from domain exceptions to JSON responses.

Author: HardMax71

backend/app/api/routes/admin/events.py

@@ -9,11 +9,9 @@
 
 from app.api.dependencies import admin_user
 from app.core.correlation import CorrelationContext
+from app.domain.admin import ReplayQuery
 from app.domain.enums.events import EventType
-from app.infrastructure.mappers import (
-    AdminReplayApiMapper,
-    EventFilterMapper,
-)
+from app.domain.events.event_models import EventFilter
 from app.schemas_pydantic.admin_events import (
     EventBrowseRequest,
     EventBrowseResponse,
@@ -28,6 +26,13 @@
 from app.schemas_pydantic.user import UserResponse
 from app.services.admin import AdminEventsService
 
+
+def _to_event_filter(pydantic_filter: AdminEventFilter) -> EventFilter:
+    """Convert Pydantic EventFilter to domain EventFilter."""
+    data = pydantic_filter.model_dump(mode="json")  # auto-converts enums to strings
+    data["text_search"] = data.pop("search_text", None)
+    return EventFilter(**data)
+
 router = APIRouter(
     prefix="/admin/events", tags=["admin-events"], route_class=DishkaRoute, dependencies=[Depends(admin_user)]
 )
@@ -36,7 +41,7 @@
 @router.post("/browse")
 async def browse_events(request: EventBrowseRequest, service: FromDishka[AdminEventsService]) -> EventBrowseResponse:
     try:
-        event_filter = EventFilterMapper.from_admin_pydantic(request.filters)
+        event_filter = _to_event_filter(request.filters)
 
         result = await service.browse_events(
             event_filter=event_filter,
@@ -79,7 +84,7 @@ async def export_events_csv(
     limit: int = Query(default=10000, le=50000),
 ) -> StreamingResponse:
     try:
-        export_filter = EventFilterMapper.from_admin_pydantic(
+        export_filter = _to_event_filter(
             AdminEventFilter(
                 event_types=event_types,
                 start_time=start_time,
@@ -111,7 +116,7 @@ async def export_events_json(
 ) -> StreamingResponse:
     """Export events as JSON with comprehensive filtering."""
     try:
-        export_filter = EventFilterMapper.from_admin_pydantic(
+        export_filter = _to_event_filter(
             AdminEventFilter(
                 event_types=event_types,
                 aggregate_id=aggregate_id,
@@ -159,7 +164,13 @@ async def replay_events(
 ) -> EventReplayResponse:
     try:
         replay_correlation_id = f"replay_{CorrelationContext.get_correlation_id()}"
-        rq = AdminReplayApiMapper.request_to_query(request)
+        rq = ReplayQuery(
+            event_ids=request.event_ids,
+            correlation_id=request.correlation_id,
+            aggregate_id=request.aggregate_id,
+            start_time=request.start_time,
+            end_time=request.end_time,
+        )
         try:
             result = await service.prepare_or_schedule_replay(
                 replay_query=rq,

backend/app/api/routes/admin/settings.py

@@ -6,11 +6,39 @@
 from pydantic import ValidationError
 
 from app.api.dependencies import admin_user
-from app.infrastructure.mappers import SettingsMapper
+from app.domain.admin import (
+    ExecutionLimits,
+    LogLevel,
+    MonitoringSettings,
+    SecuritySettings,
+    SystemSettings as DomainSystemSettings,
+)
 from app.schemas_pydantic.admin_settings import SystemSettings
 from app.schemas_pydantic.user import UserResponse
 from app.services.admin import AdminSettingsService
 
+
+def _domain_to_pydantic(domain: DomainSystemSettings) -> SystemSettings:
+    """Convert domain SystemSettings to Pydantic schema."""
+    return SystemSettings.model_validate(domain, from_attributes=True)
+
+
+def _pydantic_to_domain(schema: SystemSettings) -> DomainSystemSettings:
+    """Convert Pydantic schema to domain SystemSettings."""
+    data = schema.model_dump()
+    mon = data.get("monitoring_settings", {})
+    return DomainSystemSettings(
+        execution_limits=ExecutionLimits(**data.get("execution_limits", {})),
+        security_settings=SecuritySettings(**data.get("security_settings", {})),
+        monitoring_settings=MonitoringSettings(
+            metrics_retention_days=mon.get("metrics_retention_days", 30),
+            log_level=LogLevel(mon.get("log_level", "INFO")),
+            enable_tracing=mon.get("enable_tracing", True),
+            sampling_rate=mon.get("sampling_rate", 0.1),
+        ),
+    )
+
+
 router = APIRouter(
     prefix="/admin/settings", tags=["admin", "settings"], route_class=DishkaRoute, dependencies=[Depends(admin_user)]
 )
@@ -23,8 +51,7 @@ async def get_system_settings(
 ) -> SystemSettings:
     try:
         domain_settings = await service.get_system_settings(admin.username)
-        settings_mapper = SettingsMapper()
-        return SystemSettings(**settings_mapper.system_settings_to_pydantic_dict(domain_settings))
+        return _domain_to_pydantic(domain_settings)
 
     except Exception:
         raise HTTPException(status_code=500, detail="Failed to retrieve settings")
@@ -37,8 +64,7 @@ async def update_system_settings(
     service: FromDishka[AdminSettingsService],
 ) -> SystemSettings:
     try:
-        settings_mapper = SettingsMapper()
-        domain_settings = settings_mapper.system_settings_from_pydantic(settings.model_dump())
+        domain_settings = _pydantic_to_domain(settings)
     except (ValueError, ValidationError, KeyError) as e:
         raise HTTPException(status_code=422, detail=f"Invalid settings: {str(e)}")
     except Exception:
@@ -52,9 +78,7 @@ async def update_system_settings(
             user_id=admin.user_id,
         )
 
-        # Convert back to pydantic schema for response
-        settings_mapper = SettingsMapper()
-        return SystemSettings(**settings_mapper.system_settings_to_pydantic_dict(updated_domain_settings))
+        return _domain_to_pydantic(updated_domain_settings)
 
     except Exception:
         raise HTTPException(status_code=500, detail="Failed to update settings")
@@ -67,8 +91,7 @@ async def reset_system_settings(
 ) -> SystemSettings:
     try:
         reset_domain_settings = await service.reset_system_settings(admin.username, admin.user_id)
-        settings_mapper = SettingsMapper()
-        return SystemSettings(**settings_mapper.system_settings_to_pydantic_dict(reset_domain_settings))
+        return _domain_to_pydantic(reset_domain_settings)
 
     except Exception:
         raise HTTPException(status_code=500, detail="Failed to reset settings")

backend/app/api/routes/auth.py

@@ -1,16 +1,15 @@
-from datetime import datetime, timedelta, timezone
-from uuid import uuid4
+import logging
+from datetime import timedelta
 
 from dishka import FromDishka
 from dishka.integrations.fastapi import DishkaRoute
 from fastapi import APIRouter, Depends, HTTPException, Request, Response
 from fastapi.security import OAuth2PasswordRequestForm
 
-from app.core.logging import logger
 from app.core.security import security_service
 from app.core.utils import get_client_ip
 from app.db.repositories import UserRepository
-from app.domain.user import User as DomainAdminUser
+from app.domain.user import DomainUserCreate
 from app.schemas_pydantic.user import (
     LoginResponse,
     MessageResponse,
@@ -29,6 +28,7 @@ async def login(
     request: Request,
     response: Response,
     user_repo: FromDishka[UserRepository],
+    logger: FromDishka[logging.Logger],
     form_data: OAuth2PasswordRequestForm = Depends(),
 ) -> LoginResponse:
     logger.info(
@@ -126,6 +126,7 @@ async def register(
     request: Request,
     user: UserCreate,
     user_repo: FromDishka[UserRepository],
+    logger: FromDishka[logging.Logger],
 ) -> UserResponse:
     logger.info(
         "Registration attempt",
@@ -151,19 +152,15 @@ async def register(
 
     try:
         hashed_password = security_service.get_password_hash(user.password)
-        now = datetime.now(timezone.utc)
-        domain_user = DomainAdminUser(
-            user_id=str(uuid4()),
+        create_data = DomainUserCreate(
             username=user.username,
             email=str(user.email),
+            hashed_password=hashed_password,
             role=user.role,
             is_active=True,
             is_superuser=False,
-            hashed_password=hashed_password,
-            created_at=now,
-            updated_at=now,
         )
-        created_user = await user_repo.create_user(domain_user)
+        created_user = await user_repo.create_user(create_data)
 
         logger.info(
             "Registration successful",
@@ -204,6 +201,7 @@ async def get_current_user_profile(
     request: Request,
     response: Response,
     auth_service: FromDishka[AuthService],
+    logger: FromDishka[logging.Logger],
 ) -> UserResponse:
     current_user = await auth_service.get_current_user(request)
 
@@ -227,6 +225,7 @@ async def get_current_user_profile(
 async def verify_token(
     request: Request,
     auth_service: FromDishka[AuthService],
+    logger: FromDishka[logging.Logger],
 ) -> TokenValidationResponse:
     current_user = await auth_service.get_current_user(request)
     logger.info(
@@ -278,6 +277,7 @@ async def verify_token(
 async def logout(
     request: Request,
     response: Response,
+    logger: FromDishka[logging.Logger],
 ) -> MessageResponse:
     logger.info(
         "Logout attempt",

backend/app/api/routes/events.py

@@ -1,4 +1,5 @@
 import asyncio
+import logging
 from datetime import datetime, timedelta, timezone
 from typing import Annotated, Any, Dict, List
 
@@ -8,7 +9,6 @@
 
 from app.api.dependencies import admin_user, current_user
 from app.core.correlation import CorrelationContext
-from app.core.logging import logger
 from app.core.utils import get_client_ip
 from app.domain.enums.common import SortOrder
 from app.domain.events.event_models import EventFilter
@@ -283,6 +283,7 @@ async def delete_event(
     event_id: str,
     admin: Annotated[UserResponse, Depends(admin_user)],
     event_service: FromDishka[EventService],
+    logger: FromDishka[logging.Logger],
 ) -> DeleteEventResponse:
     result = await event_service.delete_event_with_archival(event_id=event_id, deleted_by=str(admin.email))
 
@@ -309,6 +310,7 @@ async def replay_aggregate_events(
     admin: Annotated[UserResponse, Depends(admin_user)],
     event_service: FromDishka[EventService],
     kafka_event_service: FromDishka[KafkaEventService],
+    logger: FromDishka[logging.Logger],
     target_service: str | None = Query(None, description="Service to replay events to"),
     dry_run: bool = Query(True, description="If true, only show what would be replayed"),
 ) -> ReplayAggregateResponse: