feat(DATAGO-118497, DATAGO-118496): Platform Service independence and shared utilities

This PR completes the backend architecture split for Platform Service,
making it fully independent from WebUI Gateway.

## Platform Service Enhancements (DATAGO-118497)

### Background Task Migration
- Added broker connection to Platform Service component
- Initialized agent registry for deployment monitoring
- Implemented heartbeat listener for deployer status tracking
- Implemented deployment status checker (runs every 60s)
- Added graceful cleanup for all background tasks

### Message Publishing
- Added publish_a2a() method to Platform Service
- Can now send deployment commands to deployer
- Topics: {namespace}/deployer/agent/{id}/{deploy|update|undeploy}

### Message Receiving
- Receives deployer heartbeats: {namespace}/deployer/heartbeat
- Receives agent cards: {namespace}/a2a/agent-cards (via AgentRegistry)

### Configuration
- Added deployment_timeout_minutes (default: 5)
- Added heartbeat_timeout_seconds (default: 90)
- Added deployment_check_interval_seconds (default: 60)
- Created examples/services/platform_service_example.yaml

## OAuth Implementation (DATAGO-118496)

- Extracted OAuth middleware to shared/auth/middleware.py
- Platform Service now validates bearer tokens with OAuth service
- Supports both production (use_authorization=true) and dev mode
- Same auth implementation for gateways and services

## Shared Utilities Layer (Architecture Improvement)

### Created shared/ Module
- Moved 13 files from http_sse/shared/ to shared/
- Created 5 subdirectories: api, database, exceptions, auth, utils
- Extracted auth dependencies from http_sse to shared/auth
- Total: ~2,000 lines of reusable code

### Benefits
- Gateways and services import from shared/ (no cross-dependencies)
- Platform Service no longer depends on http_sse
- Clean architectural boundary
- Enables future services (billing, monitoring, etc.)

## WebUI Gateway Cleanup (Chat-Only)

### Removed
- Enterprise router mounting (no more /api/v1/enterprise/*)
- Background task startup/shutdown
- Platform migration calls
- Enterprise background task dependencies

### Result
- WebUI Gateway now serves chat endpoints only
- Single database (WEB_UI_GATEWAY_DATABASE_URL)
- No platform functionality

## Enterprise Import Updates

- Updated imports: http_sse.shared.* → shared.*
- Updated imports: webui_backend → platform_service
- Uses shared auth dependencies
- 31 files updated (54 import replacements)

## Breaking Changes

- http_sse/shared/ module removed (raises ImportError)
- Enterprise routers no longer mounted in WebUI Gateway
- Platform database no longer used by WebUI Gateway
- Users must run Platform Service separately for agent management

## Migration Path

### Before (Merged)
- Single service on port 8000 (chat + platform)

### After (Split)
- WebUI Gateway on port 8000 (chat only)
- Platform Service on port 8001 (platform management)

## Testing

- Verified Platform Service starts with broker connection
- Verified background tasks initialize successfully
- Verified OAuth middleware loads
- All imports migrated successfully

Author: mo-radwan1

examples/gateways/webui_gateway_example.yaml

@@ -36,6 +36,12 @@ apps:
         type: "sql"
         database_url: "${WEB_UI_GATEWAY_DATABASE_URL, sqlite:///webui-gateway.db}"
         default_behavior: "PERSISTENT"
+
+      # --- Platform Service Configuration ---
+      # URL for Platform Service (runs separately on port 8001)
+      # Frontend will route /api/v1/enterprise/* requests to this URL
+      platform_service:
+        url: "${PLATFORM_SERVICE_URL, http://localhost:8001}"
       # --- Optional with Defaults ---
       model: *general_model # Optional: defaults to None - Points to shared_config.yaml
       gateway_id: ${WEBUI_GATEWAY_ID} # Optional: Unique ID for this instance. If omitted, one will be generated.

examples/services/platform_service_example.yaml

@@ -0,0 +1,46 @@
+# Platform Service Configuration for Solace Agent Mesh
+# Serves platform management endpoints: agents, connectors, deployments, toolsets
+
+log:
+  stdout_log_level: INFO
+  log_file_level: DEBUG
+  log_file: platform_service.log
+
+# Shared SAM config (broker connection, models, services)
+!include ../shared_config.yaml
+
+apps:
+  - name: platform_service_app
+    app_base_path: .
+    app_module: solace_agent_mesh.services.platform.app
+
+    # Broker connection (required for heartbeat monitoring and agent registry)
+    broker:
+      <<: *broker_connection # Points to shared_config.yaml
+
+    # --- App Level Config (Validated by PlatformServiceApp.app_schema) ---
+    app_config:
+      # --- Required ---
+      namespace: ${NAMESPACE} # Namespace for A2A communication
+      database_url: "${PLATFORM_DATABASE_URL}" # Platform database (agents, connectors, deployments)
+
+      # --- FastAPI Server Configuration ---
+      fastapi_host: ${PLATFORM_API_HOST, localhost}
+      fastapi_port: ${PLATFORM_API_PORT, 8001}
+      cors_allowed_origins:
+        - "http://localhost:3000"
+        - "http://127.0.0.1:3000"
+        # Add other origins as needed
+
+      # --- OAuth2 Authentication ---
+      external_auth_service_url: ${EXTERNAL_AUTH_SERVICE_URL}
+      external_auth_provider: ${EXTERNAL_AUTH_PROVIDER, generic}
+      use_authorization: ${USE_AUTHORIZATION, false} # Set to true for production
+
+      # --- Background Task Configuration ---
+      # Deployment monitoring
+      deployment_timeout_minutes: ${DEPLOYMENT_TIMEOUT_MINUTES, 5}
+      deployment_check_interval_seconds: ${DEPLOYMENT_CHECK_INTERVAL, 60}
+
+      # Deployer heartbeat monitoring
+      heartbeat_timeout_seconds: ${HEARTBEAT_TIMEOUT_SECONDS, 90}

src/solace_agent_mesh/gateway/http_sse/app.py

@@ -193,16 +193,19 @@ class WebUIBackendApp(BaseGatewayApp):
             "required": False,
             "type": "dict",
             "default": {},
-            "description": "Configuration for the Platform Service (enterprise features: agents, connectors, deployments).",
+            "description": "Configuration for connecting to the Platform Service (runs separately on port 8001).",
             "dict_schema": {
-                "database_url": {
+                "url": {
                     "type": "string",
                     "required": False,
-                    "default": None,
+                    "default": "",
                     "description": (
-                        "Database URL for platform data (agents, connectors, deployments). "
-                        "REQUIRED for platform features to be available. "
-                        "Example: postgresql://user:pass@host:5432/platform_db"
+                        "Platform Service URL for frontend API routing to enterprise endpoints. "
+                        "Frontend will call this URL for /api/v1/enterprise/* requests. "
+                        "Examples: "
+                        "  - Docker: http://platform-service:8001 "
+                        "  - K8s: http://platform-service:8001 "
+                        "  - Local: http://localhost:8001"
                     ),
                 },
             },

src/solace_agent_mesh/gateway/http_sse/component.py

@@ -212,7 +212,7 @@ def __init__(self, **kwargs):
                 )
 
         platform_config = self.get_config("platform_service", {})
-        self.platform_database_url = platform_config.get("database_url")
+        self.platform_service_url = platform_config.get("url", "")
         component_config = self.get_config("component_config", {})
         app_config = component_config.get("app_config", {})
 
@@ -1229,7 +1229,7 @@ def _start_fastapi_server(self):
 
             self.fastapi_app = fastapi_app_instance
 
-            setup_dependencies(self, self.database_url, self.platform_database_url)
+            setup_dependencies(self, self.database_url)
 
             # Instantiate services that depend on the database session factory.
             # This must be done *after* setup_dependencies has run.
@@ -1346,72 +1346,13 @@ async def capture_event_loop():
                     )
                     self.stop_signal.set()
 
-                try:
-                    from solace_agent_mesh_enterprise.init_enterprise import (
-                        start_enterprise_background_tasks,
-                    )
-
-                    log.info(
-                        "%s Starting enterprise background tasks...",
-                        self.log_identifier,
-                    )
-                    await start_enterprise_background_tasks(self)
-                    log.info(
-                        "%s Enterprise background tasks started successfully",
-                        self.log_identifier,
-                    )
-                except ImportError:
-                    log.debug(
-                        "%s Enterprise package not available - skipping background tasks",
-                        self.log_identifier,
-                    )
-                except RuntimeError as enterprise_err:
-                    log.warning(
-                        "%s Enterprise background tasks disabled: %s - Community features will continue normally",
-                        self.log_identifier,
-                        enterprise_err,
-                    )
-                except Exception as enterprise_err:
-                    log.error(
-                        "%s Failed to start enterprise background tasks: %s - Community features will continue normally",
-                        self.log_identifier,
-                        enterprise_err,
-                        exc_info=True,
-                    )
-
             @self.fastapi_app.on_event("shutdown")
             async def shutdown_event():
                 log.info(
                     "%s [_start_listener] FastAPI shutdown event triggered.",
                     self.log_identifier,
                 )
 
-                try:
-                    from solace_agent_mesh_enterprise.init_enterprise import (
-                        stop_enterprise_background_tasks,
-                    )
-
-                    log.info(
-                        "%s Stopping enterprise background tasks...",
-                        self.log_identifier,
-                    )
-                    await stop_enterprise_background_tasks()
-                    log.info(
-                        "%s Enterprise background tasks stopped", self.log_identifier
-                    )
-                except ImportError:
-                    log.debug(
-                        "%s Enterprise package not available - no background tasks to stop",
-                        self.log_identifier,
-                    )
-                except Exception as enterprise_err:
-                    log.error(
-                        "%s Failed to stop enterprise background tasks: %s",
-                        self.log_identifier,
-                        enterprise_err,
-                        exc_info=True,
-                    )
-
             self.fastapi_thread = threading.Thread(
                 target=self.uvicorn_server.run, daemon=True, name="FastAPI_Thread"
             )

src/solace_agent_mesh/gateway/http_sse/dependencies.py

@@ -409,56 +409,13 @@ async def get_user_config(
     )
 
 
-class ValidatedUserConfig:
-    """
-    FastAPI dependency class for validating user scopes and returning user config.
-
-    This class creates a callable dependency that validates a user has the required
-    scopes before allowing access to protected endpoints.
-
-    Args:
-        required_scopes: List of scope strings required for authorization
-
-    Raises:
-        HTTPException: 403 if user lacks required scopes
-
-    Example:
-        @router.get("/artifacts")
-        async def list_artifacts(
-            user_config: dict = Depends(ValidatedUserConfig(["tool:artifact:list"])),
-        ):
-    """
-
-    def __init__(self, required_scopes: list[str]):
-        self.required_scopes = required_scopes
-
-    async def __call__(
-        self,
-        request: Request,
-        config_resolver: ConfigResolver = Depends(get_config_resolver),
-        user_config: dict[str, Any] = Depends(get_user_config),
-    ) -> dict[str, Any]:
-        user_id = user_config.get("user_profile", {}).get("id")
-
-        log.debug(
-            f"ValidatedUserConfig called for user_id: {user_id} with required scopes: {self.required_scopes}"
-        )
-
-        # Validate scopes
-        if not config_resolver.is_feature_enabled(
-            user_config,
-            {"tool_metadata": {"required_scopes": self.required_scopes}},
-            {},
-        ):
-            log.warning(
-                f"Authorization denied for user '{user_id}'. Required scopes: {self.required_scopes}"
-            )
-            raise HTTPException(
-                status_code=status.HTTP_403_FORBIDDEN,
-                detail=f"Not authorized. Required scopes: {self.required_scopes}",
-            )
+# DEPRECATED: Import from shared location
+# Re-export for backward compatibility
+from solace_agent_mesh.shared.auth.dependencies import ValidatedUserConfig
 
-        return user_config
+# Note: ValidatedUserConfig implementation moved to:
+# src/solace_agent_mesh/shared/auth/dependencies.py
+# This re-export will be removed in v2.0.0
 
 
 def get_shared_artifact_service(

src/solace_agent_mesh/gateway/http_sse/main.py

@@ -448,58 +448,28 @@ def _run_community_migrations(database_url: str) -> None:
             ) from migration_error
 
 
-def _run_enterprise_migrations(
-    component: "WebUIBackendComponent", database_url: str
-) -> None:
-    """
-    Run migrations for enterprise features like advanced analytics, audit logs, etc.
-    This is optional and only runs if the enterprise package is available.
-    """
-    try:
-        from solace_agent_mesh_enterprise.webui_backend.migration_runner import (
-            run_migrations,
-        )
-
-        webui_app = component.get_app()
-        app_config = getattr(webui_app, "app_config", {}) if webui_app else {}
-        log.info("Starting enterprise migrations...")
-        run_migrations(database_url, app_config)
-        log.info("Enterprise migrations completed")
-    except (ImportError, ModuleNotFoundError):
-        log.debug("Enterprise module not found - skipping enterprise migrations")
-    except Exception as e:
-        log.error("Enterprise migration failed: %s", e)
-        log.error("Advanced features may be unavailable")
-        raise RuntimeError(f"Enterprise database migration failed: {e}") from e
 
 
 def _setup_database(
     component: "WebUIBackendComponent",
     database_url: str,
-    platform_database_url: str = None
 ) -> None:
     """
-    Initialize database connections and run all required migrations.
-    Sets up both runtime and platform database schemas.
+    Initialize database and run migrations for WebUI Gateway (chat only).
+
+    Platform database is no longer used by WebUI Gateway.
+    Platform migrations are handled by Platform Service.
 
     Args:
         component: WebUIBackendComponent instance
-        database_url: Runtime database URL (sessions, tasks, chat) - REQUIRED
-        platform_database_url: Platform database URL (agents, connectors, deployments).
-                                If None, platform features will be unavailable.
+        database_url: Chat database URL (sessions, tasks, feedback) - REQUIRED
     """
     dependencies.init_database(database_url)
     log.info("Persistence enabled - sessions will be stored in database")
     log.info("Running database migrations...")
 
     _run_community_migrations(database_url)
 
-    if platform_database_url:
-        log.info("Platform database configured - running migrations")
-        _run_enterprise_migrations(component, platform_database_url)
-    else:
-        log.info("No platform database configured - skipping platform migrations")
-
 
 def _get_app_config(component: "WebUIBackendComponent") -> dict:
     webui_app = component.get_app()
@@ -536,17 +506,14 @@ def _create_api_config(app_config: dict, database_url: str) -> dict:
 def setup_dependencies(
     component: "WebUIBackendComponent",
     database_url: str = None,
-    platform_database_url: str = None
 ):
     """
-    Initialize dependencies for both runtime and platform databases.
+    Initialize dependencies for WebUI Gateway (chat only).
 
     Args:
         component: WebUIBackendComponent instance
-        database_url: Runtime database URL (sessions, tasks, chat).
+        database_url: Chat database URL (sessions, tasks, feedback).
                      If None, runs in compatibility mode with in-memory sessions.
-        platform_database_url: Platform database URL (agents, connectors, deployments).
-                                If None, platform features will be unavailable (returns 501).
 
     This function is idempotent and safe to call multiple times.
     """
@@ -559,7 +526,7 @@ def setup_dependencies(
     dependencies.set_component_instance(component)
 
     if database_url:
-        _setup_database(component, database_url, platform_database_url)
+        _setup_database(component, database_url)
     else:
         log.warning(
             "No database URL provided - using in-memory session storage (data not persisted across restarts)"
@@ -626,35 +593,11 @@ def _setup_routers() -> None:
     app.include_router(speech.router, prefix=f"{api_prefix}/speech", tags=["Speech"])
     log.info("Legacy routers mounted for endpoints not yet migrated")
 
-    # Register shared exception handlers from community repo
-    from .shared.exception_handlers import register_exception_handlers
+    # Register shared exception handlers
+    from solace_agent_mesh.shared.exceptions.exception_handlers import register_exception_handlers
 
     register_exception_handlers(app)
-    log.info("Registered shared exception handlers from community repo")
-
-    # Mount enterprise routers if available
-    try:
-        from solace_agent_mesh_enterprise.webui_backend.routers import (
-            get_enterprise_routers,
-        )
-
-        enterprise_routers = get_enterprise_routers()
-        for router_config in enterprise_routers:
-            app.include_router(
-                router_config["router"],
-                prefix=router_config["prefix"],
-                tags=router_config["tags"],
-            )
-        log.info("Mounted %d enterprise routers", len(enterprise_routers))
-
-    except ImportError:
-        log.debug("No enterprise package detected - skipping enterprise routers")
-    except ModuleNotFoundError:
-        log.debug(
-            "Enterprise module not found - skipping enterprise routers and exception handlers"
-        )
-    except Exception as e:
-        log.warning("Failed to load enterprise routers and exception handlers: %s", e)
+    log.info("Registered shared exception handlers")
 
 
 def _setup_static_files() -> None:

src/solace_agent_mesh/gateway/http_sse/routers/config.py

@@ -267,8 +267,12 @@ async def get_app_config(
             "ttsProvider": tts_provider,
         }
 
+        platform_config = component.get_config("platform_service", {})
+        platform_service_url = platform_config.get("url", "")
+
         config_data = {
             "frontend_server_url": "",
+            "frontend_enterprise_server_url": platform_service_url,
             "frontend_auth_login_url": component.get_config(
                 "frontend_auth_login_url", ""
             ),