docs: add AI code generation requirements and comprehensive Google-style docstrings

- Add AI code generation requirements to AGENTS.md
- Add module-level docstrings to all 46 Python modules
- Add detailed Google-style docstrings to all classes and functions
- Remove all inline comments following self-documenting code principle
- Include Args, Returns, Raises sections in function docstrings
- Add Attributes and Examples sections to class docstrings

app/infrastructure/middleware/error_handler.py

@@ -1,4 +1,8 @@
-"""Exception handling middleware."""
+"""Exception handling middleware.
+
+This module provides exception handlers for FastAPI application.
+Maps domain exceptions to appropriate HTTP status codes.
+"""
 
 from datetime import UTC, datetime
 
@@ -17,7 +21,14 @@ from app.domain.exceptions import (
 
 
 def get_status_code(exc: DomainException) -> int:
-    """Map domain exceptions to HTTP status codes."""
+    """Map domain exceptions to HTTP status codes.
+
+    Args:
+        exc: Domain exception instance.
+
+    Returns:
+        HTTP status code for the exception type.
+    """
     match exc:
         case ValidationException():
             return 400
@@ -34,7 +45,17 @@ def get_status_code(exc: DomainException) -> int:
 
 
 async def domain_exception_handler(request: Request, exc: DomainException) -> JSONResponse:
-    """Handle domain exceptions."""
+    """Handle domain exceptions.
+
+    Converts domain exceptions to JSON error responses.
+
+    Args:
+        request: FastAPI request object.
+        exc: Domain exception instance.
+
+    Returns:
+        JSONResponse with error details.
+    """
     status_code = get_status_code(exc)
     return JSONResponse(
         status_code=status_code,
@@ -48,7 +69,17 @@ async def domain_exception_handler(request: Request, exc: DomainException) -> JS
 
 
 async def http_exception_handler(request: Request, exc: StarletteHTTPException) -> JSONResponse:
-    """Handle HTTP exceptions."""
+    """Handle HTTP exceptions.
+
+    Converts Starlette HTTP exceptions to JSON error responses.
+
+    Args:
+        request: FastAPI request object.
+        exc: Starlette HTTP exception instance.
+
+    Returns:
+        JSONResponse with error details.
+    """
     return JSONResponse(
         status_code=exc.status_code,
         content={
@@ -61,7 +92,18 @@ async def http_exception_handler(request: Request, exc: StarletteHTTPException)
 
 
 async def generic_exception_handler(request: Request, exc: Exception) -> JSONResponse:
-    """Handle generic exceptions."""
+    """Handle generic exceptions.
+
+    Converts unhandled exceptions to generic error responses.
+    Hides internal details for security.
+
+    Args:
+        request: FastAPI request object.
+        exc: Generic exception instance.
+
+    Returns:
+        JSONResponse with generic error message.
+    """
     return JSONResponse(
         status_code=500,
         content={
@@ -74,16 +116,16 @@ async def generic_exception_handler(request: Request, exc: Exception) -> JSONRes
 
 
 def register_exception_handlers(app: FastAPI) -> None:
-    """Register all exception handlers with FastAPI app."""
+    """Register all exception handlers with FastAPI app.
+
+    Args:
+        app: FastAPI application instance.
+
+    Raises:
+        TypeError: If app is not a FastAPI instance.
+    """
     if not isinstance(app, FastAPI):
         raise TypeError("app must be a FastAPI instance")
 
-    # Domain exceptions
     app.add_exception_handler(DomainException, domain_exception_handler)  # type: ignore[arg-type]
-
-    # HTTP exceptions
     app.add_exception_handler(StarletteHTTPException, http_exception_handler)  # type: ignore[arg-type]
-
-    # Generic exceptions (only in production)
-    # In development, let FastAPI show detailed traceback
-    # app.add_exception_handler(Exception, generic_exception_handler)