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/database/connection.py

@@ -1,4 +1,8 @@
-"""Database connection and session management."""
+"""Database connection and session management.
+
+This module handles database engine creation, session management,
+and connection lifecycle for the application.
+"""
 
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
@@ -13,22 +17,26 @@ from sqlalchemy.ext.asyncio import (
 from app.infrastructure.config import settings
 
 
-# Convert SQLite URL to async format if needed
 def _get_database_url() -> str:
+    """Get database URL with SQLite async compatibility.
+
+    Converts SQLite URL to async format if needed.
+
+    Returns:
+        Database URL string ready for async engine.
+    """
     url = settings.database_url
     if url.startswith("sqlite:///") and not url.startswith("sqlite+aiosqlite:///"):
         return url.replace("sqlite:///", "sqlite+aiosqlite:///")
     return url
 
 
-# Create async engine
 engine: AsyncEngine = create_async_engine(
     _get_database_url(),
     echo=settings.db.echo,
     future=True,
 )
 
-# Create session factory
 AsyncSessionLocal = async_sessionmaker(
     engine,
     class_=AsyncSession,
@@ -39,7 +47,11 @@ AsyncSessionLocal = async_sessionmaker(
 
 
 async def get_session() -> AsyncGenerator[AsyncSession]:
-    """Get database session."""
+    """Get database session.
+
+    Yields:
+        AsyncSession instance for database operations.
+    """
     async with AsyncSessionLocal() as session:
         try:
             yield session
@@ -49,7 +61,11 @@ async def get_session() -> AsyncGenerator[AsyncSession]:
 
 @asynccontextmanager
 async def get_session_context() -> AsyncGenerator[AsyncSession]:
-    """Get database session as context manager."""
+    """Get database session as context manager.
+
+    Yields:
+        AsyncSession instance for database operations.
+    """
     async with AsyncSessionLocal() as session:
         try:
             yield session
@@ -58,7 +74,11 @@ async def get_session_context() -> AsyncGenerator[AsyncSession]:
 
 
 async def init_db() -> None:
-    """Initialize database tables."""
+    """Initialize database tables.
+
+    Creates all tables defined in the metadata.
+    Should be called on application startup.
+    """
     from app.infrastructure.database.models import Base
 
     async with engine.begin() as conn:
@@ -66,5 +86,9 @@ async def init_db() -> None:
 
 
 async def close_db() -> None:
-    """Close database connections."""
+    """Close database connections.
+
+    Disposes of the engine and all connections.
+    Should be called on application shutdown.
+    """
     await engine.dispose()