# Instructor Portal Consolidation Design

## Goal

Consolidate the duplicated `teacher/*` and `instructor/*` portal flows into one canonical instructor portal so routing, navigation, Telegram deep links, and instructor-facing UI behave consistently without breaking existing access during the transition.

## Problem Summary

The codebase currently exposes two parallel instructor portals:

- `teacher/*` routes backed by `App\Livewire\Teacher\*`
- `instructor/*` routes backed by `App\Livewire\Instructor\*`

This creates overlap in navigation, inconsistent page experiences, duplicated route names, and higher maintenance risk. Some shared UI already treats both as the same workspace, but the implementation remains split.

## Scope

This phase covers only the first consolidation slice:

- Routing and redirects for `teacher/*` vs `instructor/*`
- Sidebar/topbar canonical links
- Login and Telegram deep-link destinations that currently favor `teacher.*`
- Regression tests that freeze the intended canonical behavior

This phase does not yet remove legacy `App\Livewire\Teacher\*` files or fully refactor instructor page internals.

## Non-Goals

- Rebuilding instructor UI
- Merging every instructor Livewire component in one pass
- Cleaning all notification services in the same change
- Removing backward compatibility for existing `teacher/*` links immediately

## Recommended Approach

Use `instructor/*` as the canonical portal namespace and keep `teacher/*` as a compatibility layer that redirects to the matching `instructor/*` destination when a direct mapping exists.

Why this approach:

- The newer instructor workspace already contains the richer portal direction.
- It minimizes user confusion by giving the system one canonical destination.
- It avoids breaking bookmarked links or Telegram buttons during rollout.

## Architecture

### 1. Canonical Route Policy

`instructor.*` becomes the only namespace used for:

- primary navigation
- login redirects for instructor/teacher roles
- Telegram deep links and shortcut URLs
- public header role-based dashboard links

`teacher.*` remains temporarily as a compatibility namespace. Where possible, requests to `teacher/*` should redirect to the equivalent `instructor/*` page. For legacy attendance pages that still depend on old `Teacher` components, we may preserve a limited compatibility path until the second phase.

### 2. Compatibility Mapping

Introduce a single mapping source for instructor portal route equivalence so the app does not scatter `teacher.*` to `instructor.*` conversions across controllers and views.

Responsibilities:

- define canonical dashboard route
- define route aliases for cohort, payouts, profile, and security pages
- support future cleanup of old route names

### 3. Navigation Consolidation

Portal navigation should stop linking to `teacher.*` for normal usage. The sidebar, topbar shortcuts, login redirect, and Telegram links should all resolve to canonical `instructor.*` names.

### 4. Test Strategy

Add regression tests before code changes for:

- instructor users landing on the canonical dashboard
- compatibility redirects from `teacher/*` to `instructor/*`
- shared navigation rendering canonical instructor URLs
- Telegram and auth redirect helpers resolving to canonical instructor URLs

## Error Handling

- If a legacy `teacher/*` URL has no safe equivalent yet, keep it operational rather than guessing.
- Redirect responses should preserve route parameters for mapped pages.
- Authorization continues to rely on the existing `InstructorPortalMiddleware`.

## Rollout Notes

- This is safe before production because we can normalize route behavior now instead of preserving accidental legacy contracts.
- We should still retain compatibility redirects during the first pass to avoid breaking seeded demo data, tests, and old links.

## Risks

### Risk 1: Hidden dependencies on `teacher.*`

There are likely old links in Blade, Livewire, and Telegram/webhook code paths. Mitigation: add focused search-driven cleanup in this phase and regression tests for the critical ones.

### Risk 2: Attendance flow divergence

Some attendance pages still differ between `Teacher` and `Instructor` implementations. Mitigation: only redirect routes that already have clear equivalent behavior; leave edge cases on compatibility paths until phase two.

### Risk 3: Mixed translations and labels

The UI still mixes “teacher” and “instructor” terminology. Mitigation: route consolidation first, terminology cleanup later in a separate pass.

## Acceptance Criteria

- Instructor-facing navigation points to `instructor.*` routes by default.
- Instructor login redirect resolves to the canonical instructor dashboard.
- Telegram shortcut and deep-link generation resolves to canonical instructor URLs.
- Existing `teacher/*` links that have direct equivalents redirect safely.
- Regression tests cover canonical routing and compatibility behavior.