feat(meeting): finalize meeting management with live config broadcasts

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format

app/core/api-docs.md

@@ -0,0 +1,77 @@
+# FluentMeet Core Application Documentation
+
+> **Package Location:** `/app/core`
+> **Purpose:** Houses all fundamental components that are globally shared across the entire application ecosystem, strictly agnostic of specific application models.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Configuration (`config.py`)](#configuration-configpy)
+- [Security (`security.py`)](#security-securitypy)
+- [Exception Handlers & Responses](#exception-handlers--responses)
+- [System Dependencies (`dependencies.py`)](#system-dependencies-dependenciespy)
+- [Sanitization (`sanitize.py`)](#sanitization-sanitizepy)
+
+---
+
+## Overview
+
+The `app/core` package serves as the backbone of the application. It bootstraps application config configurations asynchronously, intercepts exceptions homogeneously, drives system security schemas securely, and houses FastApi `Depends()` routines globally to evade circular imports. 
+
+---
+
+## Configuration (`config.py`)
+
+Leverages `pydantic_settings`.
+
+### The `Settings` Object
+*   Extracts natively parameters stored inside `./.env` matching dynamically against types automatically parsing logic.
+*   Resolves variables for Database URls, JWT Secrets, Redis caches, Kafka bootstrap brokers explicitly, and cloud provider APIs like OpenAI / DL environments seamlessly.
+*   Forces dynamic fallback loading the PyProject version using `tomllib`.
+
+---
+
+## Security (`security.py`)
+
+Handles cryptographic payload verification schemas explicitly without accessing Database constructs seamlessly.
+
+*   **Bcrypt Password Context:** `hash_password()` and `verify_password()`.
+    *   Implements a native exception wrapper patching standard deprecated `passlib` behaviors failing aggressively on unmanaged `bcrypt 4.0.0+` versions transparently overriding bounds dynamically.
+*   **JWT Creation (`encode`):**
+    *   `create_access_token()`: Returns a short-lived token using explicit TTL mappings native to configuration structures (expiring natively in ~60mins). 
+    *   `create_refresh_token()`: Returns a long-lived tuple returning the securely allocated JTI identifier logic explicitly mappings directly against settings (e.g., 7 days).
+
+---
+
+## Exception Handlers & Responses
+
+### Responses (`error_responses.py`)
+Standardizes REST API outputs homogenously guaranteeing frontend UI frameworks never fail parsing generic trace responses gracefully.
+
+*   `ErrorDetail`: Nested lists explicitly tracking localized parameter validation triggers dynamically.
+*   `ErrorResponse`: Unifies status, descriptor `code`, human-readable `message` securely.
+
+### Handlers (`exception_handlers.py`)
+Registered on core startup logic intercepting framework exceptions dynamically.
+
+*   Converts Starlette/FastAPI `RequestValidationError` cleanly into `400` validation constraints structures.
+*   Binds generic unhandled HTTP 500 stacks dynamically dumping details efficiently via `sanitize_for_log()`.
+
+### Custom Error Framework (`exceptions.py`)
+Developers natively invoke `raise BadRequestException("Missing ID")` mapping gracefully dynamically down to HTTP structures utilizing the Handlers. Allows custom error codes defined seamlessly (e.g. `code="INVALID_OTP"` natively mapped).
+
+---
+
+## System Dependencies (`dependencies.py`)
+
+Decouples authentication blocks natively allowing models mapping efficiently natively circumventing explicit Circular dependencies seamlessly.
+
+Provides FastApi injectable logic defining explicit Token/Bearer evaluations transparently parsing JWT variables gracefully extracting explicit target entities locally from the Database dynamically checking `is_active` flags before propagating securely to Endpoint Routers automatically.
+
+---
+
+## Sanitization (`sanitize.py`)
+
+Intercepts log mechanisms aggressively globally preventing explicit log-spoofing injection vectors smoothly intercepting inputs wrapping string payloads automatically truncating heavy lengths tracking string components securely natively tracking unmanaged inputs across routes dynamically.

app/core/config.py

@@ -1,10 +1,20 @@
+"""Application core configuration module.
+
+Leverages pydantic_settings to load variables from the `.env` file securely.
+"""
+
 import pathlib
 import tomllib
 
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
 def get_version() -> str:
+    """Extract project version from pyproject.toml natively.
+
+    Returns:
+        str: Version string (e.g. '1.0.0').
+    """
     pyproject_path = pathlib.Path(__file__).parent.parent.parent / "pyproject.toml"
     if pyproject_path.exists():
         with pyproject_path.open("rb") as f:
@@ -14,6 +24,8 @@ def get_version() -> str:
 
 
 class Settings(BaseSettings):
+    """Core settings payload mapping dynamically to .env files."""
+
     PROJECT_NAME: str = "FluentMeet"
     VERSION: str = get_version()
     API_V1_STR: str = "/api/v1"

app/core/dependencies.py

@@ -39,18 +39,20 @@ async def get_current_user(
 ) -> User:
     """Decode an access-token JWT and return the authenticated user.
 
-    Guards
-    ------
-    - Missing token          →  401
-    - Invalid / expired JWT  →  401
-    - Blacklisted JTI        →  401
-    - User not found          →  401
-    - Account soft-deleted    →  403
-    - Account deactivated     →  403
-
-    Returns
-    -------
-    The :class:`~app.auth.models.User` ORM instance.
+    Args:
+        token (str | None): OAuth2 password bearer token. 
+            Defaults to Depends(oauth2_scheme).
+        bearer (HTTPAuthorizationCredentials | None): HTTP bearer credentials. 
+            Defaults to Depends(bearer_scheme).
+        db (Session): Database session.
+        token_store (TokenStoreService): Redis-backed token store service.
+
+    Raises:
+        UnauthorizedException: If missing token, invalid JWT, revoked JTI, or not found.
+        ForbiddenException: If the account is soft-deleted or deactivated.
+
+    Returns:
+        User: The authenticated User ORM instance.
     """
     # Prefer Bearer token if provided (e.g. from 'HTTP Bearer' field in Swagger)
     # otherwise fall back to OAuth2 token (from 'Authorize' login form).
@@ -125,7 +127,19 @@ async def get_current_user_optional(
     db: Session = Depends(get_db),
     token_store: TokenStoreService = Depends(get_token_store_service),
 ) -> User | None:
-    """Attempt to decode JWT and return User if present, otherwise return None."""
+    """Attempt to decode JWT and return User if present, otherwise return None.
+
+    Args:
+        token (str | None): OAuth2 password bearer token. 
+            Defaults to Depends(oauth2_scheme).
+        bearer (HTTPAuthorizationCredentials | None): HTTP bearer credentials. 
+            Defaults to Depends(bearer_scheme).
+        db (Session): Database session.
+        token_store (TokenStoreService): Redis-backed token store service.
+
+    Returns:
+        User | None: The authenticated User ORM instance or None if missing/invalid.
+    """
     try:
         user = await get_current_user(
             token=token, bearer=bearer, db=db, token_store=token_store

app/core/error_responses.py

@@ -1,3 +1,8 @@
+"""Standardized API Error Response architectures module.
+
+Defines Pydantic representations guaranteeing frontend API structures respond homogenously.
+"""
+
 from typing import Any
 
 from fastapi.responses import JSONResponse
@@ -13,7 +18,7 @@ class ErrorResponse(BaseModel):
     status: str = "error"
     code: str
     message: str
-    details: list[ErrorDetail] = []
+    details: list[Any] = []
 
 
 def create_error_response(
@@ -22,20 +27,32 @@ def create_error_response(
     message: str,
     details: list[dict[str, Any]] | None = None,
 ) -> JSONResponse:
-    """
-    Helper to create a standardized JSON error response.
+    """Helper to create a standardized JSON error response.
+
+    Args:
+        status_code (int): HTTP status code targeting fastAPI.
+        code (str): Application specific string error code identifier.
+        message (str): Human-readable exception descriptor.
+        details (list[dict[str, Any]] | None): Additional list of error dictionaries
+            defining problem fields. Defaults to None.
+
+    Returns:
+        JSONResponse: Standardized FastAPI JSON response strictly bound to ErrorResponse schema.
     """
     error_details = []
     if details:
         for detail in details:
-            error_details.append(
-                ErrorDetail(
-                    field=detail.get("field"),
-                    message=detail.get("msg")
-                    or detail.get("message")
-                    or "Unknown error",
+            if "msg" in detail and "field" in detail:
+                # Map FastApi Validation Errors explicitly
+                error_details.append(
+                    {
+                        "field": detail.get("field"),
+                        "message": detail.get("msg") or "Validation error",
+                    }
                 )
-            )
+            else:
+                # Preserve standard custom metadata cleanly
+                error_details.append(detail)
 
     response_content = ErrorResponse(
         status="error",

app/core/exception_handlers.py

@@ -1,3 +1,9 @@
+"""Global Application HTTP Exception handlers module.
+
+Exposes standard handler signatures intercepting Starlette and native Python blocks
+returning homogeneous `create_error_response` models dynamically.
+"""
+
 import logging
 from typing import Any
 
@@ -14,8 +20,14 @@
 
 
 async def fluentmeet_exception_handler(_request: Request, exc: Any) -> JSONResponse:
-    """
-    Handler for all custom FluentMeetException exceptions.
+    """Handler for all custom FluentMeetException exceptions.
+
+    Args:
+        _request (Request): Starlette HTTP Request.
+        exc (Any): Instance derived via `FluentMeetException`.
+
+    Returns:
+        JSONResponse: An ErrorResponse mapping to `exc.status_code`.
     """
     return create_error_response(
         status_code=exc.status_code,
@@ -26,8 +38,15 @@ async def fluentmeet_exception_handler(_request: Request, exc: Any) -> JSONRespo
 
 
 async def validation_exception_handler(_request: Request, exc: Any) -> JSONResponse:
-    """
-    Handler for Pydantic validation errors (422 -> 400).
+    """Handler for Pydantic validation errors (422 -> 400).
+
+    Args:
+        _request (Request): Starlette HTTP Request.
+        exc (Any): FastApi `RequestValidationError` block.
+
+    Returns:
+        JSONResponse: HTTP 400 error dynamically defining all Pydantic field 
+            failures natively.
     """
     details = []
     for error in exc.errors():
@@ -47,8 +66,14 @@ async def validation_exception_handler(_request: Request, exc: Any) -> JSONRespo
 
 
 async def http_exception_handler(_request: Request, exc: Any) -> JSONResponse:
-    """
-    Handler for Starlette/FastAPI HTTP exceptions.
+    """Handler for Starlette/FastAPI HTTP exceptions.
+
+    Args:
+        _request (Request): Starlette HTTP Request.
+        exc (Any): Catch-all for standard HTTP 4xx overrides block mechanisms.
+
+    Returns:
+        JSONResponse: A mapped fallback response retaining the `exc.status_code`.
     """
     return create_error_response(
         status_code=exc.status_code,
@@ -60,8 +85,15 @@ async def http_exception_handler(_request: Request, exc: Any) -> JSONResponse:
 async def unhandled_exception_handler(
     _request: Request, exc: Exception
 ) -> JSONResponse:
-    """
-    Handler for all other unhandled exceptions (500).
+    """Handler for all other unhandled exceptions (500).
+
+    Args:
+        _request (Request): Starlette HTTP Request.
+        exc (Exception): Standard fatal Python runtime exception mapping.
+
+    Returns:
+        JSONResponse: Protected HTTP 500 entity guarding system stacktraces 
+            from external clients statically.
     """
     logger.exception("Unhandled exception occurred: %s", sanitize_for_log(exc))
     return create_error_response(
@@ -72,8 +104,11 @@ async def unhandled_exception_handler(
 
 
 def register_exception_handlers(app: FastAPI) -> None:
-    """
-    Register all custom exception handlers to the FastAPI app.
+    """Register all custom exception handlers to the FastAPI app.
+
+    Args:
+        app (FastAPI): The main application context container natively 
+            targeting startup hooks framework.
     """
     app.add_exception_handler(FluentMeetException, fluentmeet_exception_handler)
     app.add_exception_handler(RequestValidationError, validation_exception_handler)

app/core/exceptions.py

@@ -1,9 +1,23 @@
+"""Application Base Exceptions module.
+
+Defines the core `FluentMeetException` structure allowing handlers to easily map
+application failures directly to standardized HTTP 400 and 500 entity wrappers natively.
+"""
+
 from typing import Any
 
 
 class FluentMeetException(Exception):
-    """
-    Base exception for all FluentMeet API errors.
+    """Base exception for all FluentMeet API errors.
+
+    Attributes:
+        status_code (int): Standard HTTP binding natively decoded by handlers.
+        code (str): Explicit mapped exception code array dynamically returned 
+            to frontend structures.
+        message (str): Text definition descriptor structure readable 
+            explicitly by users.
+        details (list[dict[str, Any]]): Internal mappings definition blocks 
+            (useful for validation outputs).
     """
 
     def __init__(

app/core/init_admin.py

@@ -1,3 +1,8 @@
+"""Initialization module for default system admin user.
+
+Triggers an automatic account creation using environment variables.
+"""
+
 import logging
 
 from sqlalchemy import select
@@ -12,6 +17,11 @@
 
 
 def init_admin(db: Session) -> None:
+    """Initialize a default admin account on server startup natively.
+
+    Args:
+        db (Session): Database transaction session.
+    """
     if not settings.ADMIN_EMAIL or not settings.ADMIN_PASSWORD:
         logger.info(
             "Admin credentials not fully set in .env, skipping admin initialization."

app/core/rate_limiter.py

@@ -1,3 +1,8 @@
+"""API Route Rate Limiter configuration module.
+
+Leverages slowapi to configure IP-based throttling across global routes natively.
+"""
+
 from fastapi import Request
 from fastapi.responses import JSONResponse
 from slowapi import Limiter
@@ -13,6 +18,16 @@ async def rate_limit_exception_handler(
     _request: Request,
     _exc: RateLimitExceeded,
 ) -> JSONResponse:
+    """Handle Rate Limit errors converting them to standardized HTTP 429 schemas.
+
+    Args:
+        _request (Request): Starlette HTTP request mapping object.
+        _exc (RateLimitExceeded): Fastapi Limiter exceeded bounds exception 
+            tracking model.
+
+    Returns:
+        JSONResponse: Standardized HTTP 429 JSONResponse entity.
+    """
     return create_error_response(
         status_code=429,
         code="RATE_LIMIT_EXCEEDED",