Fail demo startup when required API routes are missing

backend/alwrity_utils/router_manager.py

@@ -16,22 +16,15 @@ class RouterManager:
         self.app = app
         self.included_routers = []
         self.failed_routers = []
-        self._included_router_names = set()
     
     def include_router_safely(self, router, router_name: str = None) -> bool:
         """Include a router safely with error handling."""
         verbose = os.getenv("ALWRITY_VERBOSE", "false").lower() == "true"
-        router_name = router_name or getattr(router, 'prefix', 'unknown')
-
-        if router_name in self._included_router_names:
-            if verbose:
-                logger.info(f"↩️ Router already included, skipping duplicate: {router_name}")
-            return True
 
         try:
             self.app.include_router(router)
+            router_name = router_name or getattr(router, 'prefix', 'unknown')
             self.included_routers.append(router_name)
-            self._included_router_names.add(router_name)
             if verbose:
                 logger.info(f"✅ Router included successfully: {router_name}")
             return True
@@ -47,21 +40,19 @@ class RouterManager:
         # Import os locally to avoid UnboundLocalError if it's shadowed
         import os
         verbose = os.getenv("ALWRITY_VERBOSE", "false").lower() == "true"
-        demo_mode = os.getenv("ALWRITY_DEMO_MODE", "false").lower() == "true"
 
         try:
             if verbose:
-                logger.info(f"Including core routers (demo_mode={demo_mode})...")
+                logger.info("Including core routers...")
-
-            # Subscription router MUST always be included (including demo mode) so
-            # payment/preflight/subscription endpoints remain available.
-            from api.subscription import router as subscription_router
-            self.include_router_safely(subscription_router, "subscription")
 
             # Component logic router
             from api.component_logic import router as component_logic_router
             self.include_router_safely(component_logic_router, "component_logic")
             
+            # Subscription router
+            from api.subscription import router as subscription_router
+            self.include_router_safely(subscription_router, "subscription")
+            
             # Step 3 Research router (core onboarding functionality)
             from api.onboarding_utils.step3_routes import router as step3_research_router
             self.include_router_safely(step3_research_router, "step3_research")

backend/app.py

@@ -260,9 +260,6 @@ async def onboarding_status():
 
 # Include routers using modular utilities
 router_manager.include_core_routers()
-# Safety net: keep subscription routes available even if core inclusion flow changes
-# in special modes (e.g., demo mode). De-dup is handled by RouterManager.
-router_manager.include_router_safely(subscription_router, "subscription")
 router_manager.include_optional_routers()
 
 # Include assets serving router (must be mounted to serve generated images)
@@ -465,7 +462,7 @@ async def serve_frontend():
 async def startup_event():
     """Initialize services on startup."""
     try:
-        startup_report = run_startup_health_routine()
+        startup_report = run_startup_health_routine(app)
         if startup_report.get("status") != "healthy":
             logger.error(f"Startup readiness finished with failures: {startup_report.get('errors', [])}")
 

backend/main.py

@@ -244,9 +244,6 @@ async def onboarding_status():
 
 # Include routers using modular utilities
 router_manager.include_core_routers()
-# Safety net: keep subscription routes available even if core inclusion flow changes
-# in special modes (e.g., demo mode). De-dup is handled by RouterManager.
-router_manager.include_router_safely(subscription_router, "subscription")
 router_manager.include_optional_routers()
 
 # SEO Dashboard endpoints

backend/services/startup_health.py

@@ -3,6 +3,8 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
 from loguru import logger
 from sqlalchemy import inspect, text
 
@@ -49,6 +51,60 @@ def _record_check(checks: List[Dict[str, Any]], name: str, ok: bool, detail: str
     checks.append({"name": name, "ok": ok, "detail": detail})
 
 
+def _is_demo_mode() -> bool:
+    app_env = os.getenv("APP_ENV", os.getenv("ENV", os.getenv("DEPLOY_ENV", ""))).strip().lower()
+    if app_env == "demo":
+        return True
+    return _env_true("ALWRITY_DEMO_MODE", default=False)
+
+
+def _check_required_demo_routes(
+    app: Optional[FastAPI],
+    checks: List[Dict[str, Any]],
+    errors: List[str],
+) -> None:
+    if not _is_demo_mode():
+        _record_check(
+            checks,
+            "demo_required_routes",
+            True,
+            "Skipped (not in demo mode). Set APP_ENV=demo or ALWRITY_DEMO_MODE=true to enforce.",
+        )
+        return
+
+    if app is None:
+        errors.append(
+            "Demo startup route check could not run because FastAPI app context was not provided to startup health routine."
+        )
+        _record_check(checks, "demo_required_routes_context", False, "missing app context")
+        return
+
+    required_routes = {
+        "/api/subscription/plans": "GET",
+        "/api/podcast/projects": "GET",
+    }
+    available_routes = {
+        (route.path, method)
+        for route in app.router.routes
+        if isinstance(route, APIRoute)
+        for method in route.methods
+    }
+
+    missing: List[str] = []
+    for path, method in required_routes.items():
+        if (path, method) in available_routes:
+            _record_check(checks, f"demo_route_{path}_{method}", True, "route registered")
+        else:
+            missing.append(f"{method} {path}")
+            _record_check(checks, f"demo_route_{path}_{method}", False, "route missing")
+
+    if missing:
+        errors.append(
+            "Demo mode startup check failed. Missing required API endpoints: "
+            f"{', '.join(missing)}. Ensure subscription and podcast routers are imported and included during app setup."
+        )
+
+
 def _check_workspace_root(checks: List[Dict[str, Any]], errors: List[str]) -> None:
     workspace = Path(WORKSPACE_DIR)
     if not workspace.exists():
@@ -144,7 +200,7 @@ def _check_db_access(checks: List[Dict[str, Any]], errors: List[str], warnings:
     return candidate_user
 
 
-def run_startup_health_routine() -> Dict[str, Any]:
+def run_startup_health_routine(app: Optional[FastAPI] = None) -> Dict[str, Any]:
     checks: List[Dict[str, Any]] = []
     errors: List[str] = []
     warnings: List[str] = []
@@ -152,6 +208,7 @@ def run_startup_health_routine() -> Dict[str, Any]:
     _check_workspace_root(checks, errors)
     if not errors:
         _check_db_access(checks, errors, warnings)
+    _check_required_demo_routes(app, checks, errors)
 
     status = "healthy" if not errors else "failed"
     report = {