Clarify settings and app wiring

app/backend/core/config.py

@@ -1,16 +1,20 @@
 """Environment configuration derived from environment variables."""
 
 from functools import lru_cache
+from pydantic import SecretStr # Import SecretStr for sensitive data
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 class Settings(BaseSettings):
-    """Application settings."""
+    """
+    Application settings class using Pydantic BaseSettings.
+    Settings are loaded from environment variables and have default values defined here.
+    """
 
-    service_name: str = "avaaz-backend" # Used as a functional ID
-    environment: str = "development"
+    service_name: str = "avaaz-backend" # A unique functional identifier for the microservice
+    environment: str = "development" # Defines the current deployment stage (e.g., 'development', 'staging', 'production')
 
     title: str = "Avaaz Language Tutoring API"
-    description: str ="""
+    description: str = """
         # Avaaz Language Tutoring API
 
         This API powers the **avaaz.ai** mobile and web applications, providing the robust backend services for our AI-driven oral language skills tutor. The platform is specifically engineered to help students achieve oral proficiency using adaptive, conversational AI agents.
@@ -22,14 +26,24 @@ class Settings(BaseSettings):
         *   **Cross-Platform Sync:** Ensures seamless learning continuity and progress synchronization across all user devices.
         """
     
-    version: str = "0.1.0" 
+    version: str = "0.1.0" # The current semantic version of the API application
     
-    database_url: str = "postgresql+psycopg://postgres:postgres@postgres:5432/avaaz"
-
-    model_config = SettingsConfigDict(env_prefix="", case_sensitive=False)
+    # Use SecretStr to prevent accidental logging of credentials.
+    # Access the actual value using settings.database_url.get_secret_value()
+    database_url: SecretStr = SecretStr("postgresql+psycopg://postgres:postgres@postgres:5432/avaaz")
 
+    model_config = SettingsConfigDict(
+        env_prefix="",  # Load variables without a specific prefix (e.g., `DATABASE_URL` instead of `APP_DATABASE_URL`)
+        case_sensitive=False # Environment variable names are treated as case-insensitive during loading
+    )
 
 @lru_cache(maxsize=1)
 def get_settings() -> Settings:
-    """Return cached settings instance."""
+    """
+    Return a cached singleton instance of the application settings.
+    
+    This function leverages functools.lru_cache to ensure that environment variables
+    are read only once during the application's lifecycle, improving performance
+    and ensuring consistency across requests.
+    """
     return Settings()