---
title: "Legacy Platform Redirection"
slug: "legacy-platform-redirection"
updated: 2026-10-08T06:17:41Z
published: 2026-10-08T06:17:41Z
canonical: "docs.viewlift.com/legacy-platform-redirection"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viewlift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Legacy Platform Redirection

## 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](https://cdn.document360.io/15e0c142-c823-4c77-a8e8-9d32ca937982/Images/Documentation/Screenshot%202026-08-26%20at%201.18.32%E2%80%AFPM.png)

## 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.