Press CTRL+K to open search

Legacy Platform Redirection

  • Published on Aug 26, 2026
  • 2 minute(s) read
  • G
 Prev Next

Legacy Platform Redirection

Implementation, debugging, and operational runbook for temporary OneCMS-to-legacy handoff.

Decision Reference

This document operationalizes ADR-026: Legacy Platform Redirection Control Plane.

ADR-026 defines why this exists and when it must be removed.
This page defines how it works at runtime and how to debug issues.

Runtime Control Flow

Image

Configuration Contract

OneCMS

System Variable Purpose Contract / Debug Note
OneCMS (new CMS) NEXT_PUBLIC_PLATFORM_LEGACY_BASE_URL Base URL of legacy platform. Used as the foundation for all legacy redirect URLs.
OneCMS (new CMS) NEXT_PUBLIC_PLATFORM_LEGACY_BASE_PATH Legacy entry path for root handoff. Used by resolveLegacyPlatformUrl(); client-specific entries may differ (for example /analytics vs /content).
OneCMS (new CMS) NEXT_PUBLIC_BASE_PATH Next.js base path for OneCMS deployment. Infra-level boundary between new CMS and legacy deployment footprint.
OneCMS (new CMS) NEXT_PUBLIC_REDIRECT__TO_LEGACY_PLATFORM Master switch for legacy handoff behavior. true enables helper-based legacy redirect flow; false keeps OneCMS-native routing.
OneCMS (new CMS) NEXT_PUBLIC_WHITELIST_DOMAINS Domain allowlist for cookie scope across handoff. Critical for auth/session continuity across domains, especially OAuth auth_state validation after new-CMS-to-legacy handoff.

Legacy CMS

System Variable Purpose Contract / Debug Note
Legacy CMS (old CMS) NEXT_PUBLIC_REDIRECT_TO_ONECMS Legacy-side switch for redirecting to OneCMS. false keeps users on legacy; true enables handoff toward OneCMS.
Legacy CMS (old CMS) NEXT_PUBLIC_ONECMS_BASE_PATH OneCMS path target used by legacy handoff. Must match OneCMS NEXT_PUBLIC_BASE_PATH exactly.

Implementation Touchpoints

Config and helper boundary

  • src/config/config.ts
  • src/lib/helpers/navigation/internalRedirectResolver.ts

Main helper responsibilities

internalRedirectResolver(pathId, path)
Controls route-level path mapping to legacy destinations.

resolveLegacyPlatformUrl()
Resolves root handoff URL for login/logout/entry redirects.

resolveLegacyPlatformDeepLinking(permalink)
Appends legacy permalink to legacy base URL for deep-link review flows.

Current call sites

  • src/config/routesConfig.ts (sidebar/internal navigation)
  • src/adapters/permissions/landingPathResolver.adapter.ts (post-auth landing)
  • src/hooks/auth/useAuth.ts (logout handoff)
  • src/modules/overview-dashboard/widgets/video-errors/index.tsx (review deep links)

Runbook

1. Enable legacy handoff from OneCMS

  • Set NEXT_PUBLIC_REDIRECT__TO_LEGACY_PLATFORM=true.
  • Confirm NEXT_PUBLIC_PLATFORM_LEGACY_BASE_URL is reachable.
  • Confirm NEXT_PUBLIC_PLATFORM_LEGACY_BASE_PATH points to the expected legacy entry path.

2. Disable legacy handoff from OneCMS

  • Set NEXT_PUBLIC_REDIRECT__TO_LEGACY_PLATFORM=false.
  • Verify routing remains in OneCMS and no window.location.href handoffs occur.

3. Validate old/new CMS interop

  • Ensure old CMS NEXT_PUBLIC_ONECMS_BASE_PATH matches OneCMS NEXT_PUBLIC_BASE_PATH exactly.
  • Ensure old CMS NEXT_PUBLIC_REDIRECT_TO_ONECMS is consistent with rollout intent.

4. OAuth/auth_state failures after handoff

Symptoms:

  • OAuth callback errors related to auth_state mismatch.

Checks:

  • Verify NEXT_PUBLIC_WHITELIST_DOMAINS includes all required domains for cookie sharing.
  • Verify callback hosts and base paths align with current environment.
  • Verify redirect direction flags are not conflicting between new and old CMS.

5. Wrong landing path after sign-in or new-tab open

Checks:

  • Verify NEXT_PUBLIC_REDIRECT__TO_LEGACY_PLATFORM.
  • Verify NEXT_PUBLIC_PLATFORM_LEGACY_BASE_URL and NEXT_PUBLIC_PLATFORM_LEGACY_BASE_PATH.
  • Verify cookie redirectTo is expected and authorized.

6. Incorrect deep-link URL from dashboard review actions

Checks:

  • Verify input permalink from backend is already legacy-compatible.
  • Verify resolveLegacyPlatformDeepLinking output for current environment values.

Test Coverage

Behavior is validated in:

  • src/__tests__/lib/helpers/navigation/internalRedirectResolver.test.ts
  • src/__tests__/adapters/permissions/landingPathResolver.test.ts

Sunset Plan

When legacy is fully decommissioned:

  1. Create a superseding ADR that closes migration-era redirection.
  2. Set redirect to false and observe behavior.
  3. Once stable, remove redirectToLegacyPlatform branching and legacy helper usage.
  4. Remove legacy-specific environment variables and stale runbook content.
  5. Update this page to mark it deprecated.

:::danger Sunset Note
Once migration is completed and the legacy to onecms redirection is disabled, and legacy is shutdown, do not delete this document, or ADR-026. Only mark both as deprecated.
:::