ADR-026: Legacy Platform Redirection Control Plane

Context

OneCMS is currently operating in a migration window where both the new CMS and legacy platform are active.

During this period, some navigation and post-auth flows must route users to legacy URLs, while others continue to resolve inside OneCMS. The same user journey can enter from multiple points (sidebar routes, auth landing, dashboard deep links), so ad hoc redirection logic makes behavior hard to reason about and debug.

A single, explicit control plane is required so teams can:

• understand exactly when legacy redirection is enabled
• trace how each redirect URL is resolved
• disable the behavior safely when migration completes

Decision

Legacy redirection is governed by a single feature switch and a dedicated helper boundary.

1. The canonical switch is Config.Platform.redirectToLegacyPlatform (NEXT_PUBLIC_REDIRECT__TO_LEGACY_PLATFORM).
2. Redirection helpers in internalRedirectResolver.ts are the only place that maps OneCMS navigation intent to legacy URLs:
   • internalRedirectResolver(pathId, path) resolves sidebar/internal route targets through a controlled path map.
   • resolveLegacyPlatformUrl() resolves the legacy platform root handoff URL using legacy base URL and base path.
   • resolveLegacyPlatformDeepLinking(permalink) resolves deep links by appending backend permalink paths to the legacy base URL.
3. Call sites must consume these helpers instead of building legacy URLs inline:
   • route config and internal navigation links use internalRedirectResolver
   • post-auth default landing and logout handoff use resolveLegacyPlatformUrl
   • overview dashboard video error review links use resolveLegacyPlatformDeepLinking
4. When the switch is disabled, all helper functions fall back to OneCMS-native paths/behavior.
5. When migration is complete and legacy is decommissioned, this control plane is removed via a superseding ADR and code cleanup.

Consequences

• Enables deterministic behavior across all legacy handoff entry points.
• Centralizes debugging to one switch, one config surface, and one helper module.
• Reduces drift between navigation, auth landing, and deep-link flows.
• Accepts temporary complexity (dual-path logic and legacy path mapping) during migration.
• Requires disciplined cleanup after cutover to avoid carrying dead migration logic.

Notes

Superseded by:

• ADR-034: OneCMS-First Auth Routing and Scoped Legacy Redirection

Implementation details, runtime flow, environment matrix, and debugging runbook are documented in:

• Core Platform: Legacy Platform Redirection

Sunset trigger:

• Once legacy platform traffic is fully cut over, create a new ADR that supersedes this one and removes legacy redirection helpers/call sites.