jobtrackingapp/docs/redesign/phase-5/NAVIGATION_MIGRATION.md

# Navigation migration

P5-07 successor: `/analytics` is now the authenticated **Insights → Analytics** destination with the retained existing reports. The 31 original patterns below remain, plus this one addition (32 total). Dashboard stays `/dashboard`; its old Analytics breadcrumb is corrected to Home → Dashboard. Analytics uses Home → Insights → Analytics, with the supported 6/12/24-month selection in `?months=`. [Implementation/evidence](p5-07/README.md). No Documents/Admin destination or expanded command catalogue is implied; earlier planning text below remains historical.

Source: current [App](../../../job-tracker-ui/src/App.tsx), [AppShell](../../../job-tracker-ui/src/layout/AppShell.tsx), [Phase 3 route contract](../phase-3/ROUTE_PLAN.md). P5-01 changes navigation presentation; it does not replace the router, providers or page owners.

## P5-01 visible shell contract

Use the existing 254px expanded / 84px collapsed sidebar and <768px modal drawer as starting dimensions. Use MUI semantic navigation/surface/action/focus tokens and P4 typography/gutters. Existing provisional indigo, Archivo/system type, name and mark remain substitutable; no final branding decision. Calm neutral surfaces, restrained borders/depth, compact labelled groups and useful content width; no gradient/glass treatment, new card grid or giant heading.

Desktop: sidebar identity, Dashboard, Job search, Career, Account, authorized Admin; utility bar contains command trigger, bell and account access. Insights is inserted only when P5-07 supplies real content. One contextual title below utilities, no repeated page/job/CV header. Keep existing width opt-ins (Settings reading; other pages unchanged until migrated). No second theme/preferences store.

Expanded primary rows: icon + name + selected indicator; selected and keyboard focus remain distinct. Group labels are quiet but readable, not color-only. Child destinations use an indented, labelled secondary list under their owner. Retain reminder count. Collapsed rail keeps accessible names and readable tooltips; Jobs/Settings/Admin secondary destinations remain reachable via a keyboard-operable labelled menu, not hover-only. Selecting a child marks its parent current while identifying the actual child. Career Profile and CVs require explicit matching so `/career/builder/:id` never highlights Career Profile.

Mobile: full visible labels regardless of desktop collapse, one modal drawer with all groups/children in scrollable flow; no app-bar overlay on first focus, no nested traps. Global search/bell/account remain reachable; long version/name moves into the account disclosure when necessary, with the same authorized information. Closing returns focus; successful navigation focuses the destination heading; cancelled dirty navigation preserves draft/focus. Skip-to-main and navigation landmarks must be real. No bottom navigation added.

Keep existing children visible in shell secondary navigation until their workspace offers a proven replacement. A move is atomic: new reachable destination and tests land before removal of its old entry. P5-03 may introduce a Jobs secondary row, without duplicating those as new **primary** destinations. Narrow secondary rows use the existing labelled-selector pattern. Job detail gets Jobs/Back context, not two stacked navigation bars plus its tabs.

## Every current menu and utility entry

| Current entry | P5-01 home / initial behavior | Later disposition / condition | PRES |
|---|---|---|---|
| Dashboard | Ungrouped Home primary, `/dashboard` | Same route, P5-06 content | E07, S01, S02 |
| Job applications | Job search → Jobs primary, `/jobs` | Tracked Table default; P5-03 | J03–J06 |
| Discover jobs | Jobs secondary, `/discover` | Jobs secondary row; discovery owner unchanged | J01, J02 |
| Reminders + count | Jobs secondary, label Follow-ups, `/reminders` | Retain count and all reasons, not just overdue rows | W11 |
| Kanban board | Jobs view switch, `/jobs?view=board`; `/kanban` retained | P5-04b integrates after proven parity; alias replaces history and preserves query/hash/state | J07 |
| Companies | Jobs secondary, `/companies` | Preserve `?edit=id`, contacts/history | J08 |
| Offer comparison | Jobs secondary, `/offers` | Retain recorded offer comparison, no new salary model | J09 |
| Job email / Correspondence | Job search → Correspondence **primary**, `/correspondence` | Inbox, Drafts, Review remain independent; not hidden in Documents | M01–M06 |
| Career workspace | Career → Career Profile, `/career` | Canonical facts; page remains Phase 7 | C01–C04 |
| CV Builder | Career → CVs, `/career/builder` | Library retained, editor P5-09+ gated | C05–C12 |
| Trash | Jobs secondary utility, `/trash` | Explicit reachable label; P5-03 table reuse; no permanent delete | J06 |
| Audit log | Authorized Admin → Audit, `/admin/audit` | No empty `/admin` landing or aggregate user scraping | A02 |
| Users | Authorized Admin → Users, `/admin/users` | Admin group trigger may open children, not an invented dashboard | A01 |
| System | Authorized Admin → System, `/admin/system` | Retain operational tools, not personal analytics | A03 |
| Profile | Settings secondary + account menu → Account & security, `/profile` | Remove duplicate primary only with both accessible links present; no form relocation | E04–E06 |
| Settings | Account → Settings primary, `/settings` | Existing tabs and mobile selector retained | S03–S05, J10 |
| Account-menu profile/settings/sign out | Account menu, same callbacks | Appearance/language shortcuts reuse current handlers; no new auth/session owner | E05–E09 |
| Current language/theme controls | Remain reachable in shell/account area | Existing preferences; UI locale distinct from CV document locale | E08, S03 |
| Quick search; six commands; job/company results | Same trigger + Ctrl/Cmd+K in P5-01 | P5-02 presentation/keyboard/error improvements; no missing future commands | E07, J03, J08 |
| Bell / unread count | Same NotificationsPopover and store | P5-02 recent-list presentation, no new producer | S02, W11, W12 |
| Operations from notifications/workflow | Utility in notification/account activity access, `/operations` | Keep progress/retry/cancel reachable; no admin conflation | W12 |
| Connected accounts from Settings | Settings secondary/account connection link, `/settings/connected-accounts` | Mail/calendar grants remain distinct from sign-in linking | M06, E03 |
| Add job on Jobs + command Add + capture links | Retain existing AddJobModal/open callbacks and query review | No automatic creation by route mounting or palette activation | J03, J04 |
| Admin version/commit metadata | Admin-only account/header disclosure, responsive | Keep both values available; no public operational metadata expansion | A03, E07 |

Proposed but absent: **Documents** waits for bounded owner-scoped cross-job metadata reads and package proof (Phase 7/NEW-11); **Analytics** becomes meaningful in P5-07; expanded **Notifications** route is deferred; aggregate **Admin dashboard** needs NEW-08/OD-09. Do not show dead/disabled placeholders or claim a complete Documents index. Existing job Documents/CV links stay reachable. Contextual AI stays in its real domain; no global AI page/panel is added by this shell plan.

## All 31 original patterns retained; one Analytics addition

No compatibility removal date is approved. Each row retains refresh, direct entry, authorization and safe error behavior. Wildcard/fallback infrastructure and inner root redirect also remain but are not counted as pages. The P5-07 `/analytics` addition makes **32** patterns; `/kanban` remains counted even if later an alias.

| Current pattern | P5 destination / compatibility decision | Owner slice | PRES |
|---|---|---|---|
| `/` | Public landing / existing authenticated redirect unchanged | 01 regression only | E01 |
| `/login` | Existing auth/challenge entry | 01 regression only | E02–E04 |
| `/register` | Existing configured registration | 01 regression only | E02 |
| `/forgot-password` | Existing reset request | 01 regression only | E02 |
| `/reset-password` | Existing token query | 01 regression only | E02 |
| `/verify-email` | Existing token query | 01 regression only | E02 |
| `/confirm-email-change` | Existing pending identity confirmation | 01 regression only | E06 |
| `/microsoft-legacy-relink` | Existing recovery/relink | 01 regression only | E03 |
| `/cv/:slug` | Published-only public page/PDF, never numeric redirect | 09–14 regression | C05, C12 |
| `/dashboard` | Home | 06, 07 | S01, S02 |
| `/analytics` (P5-07 addition) | Insights → existing personal reports | 07 | S01, S02, E07–E09, J05/J09 |
| `/discover` | Jobs → Discover | 01, 03 link only | J01, J02 |
| `/jobs` | Jobs → Tracked; Table default | 03, 04b | J03–J07 |
| `/jobs/:id` | Dedicated job workspace | 08a, 08b | W01–W12, M01, M02 |
| `/reminders` | Jobs → Follow-ups | 01 link only | W11 |
| `/operations` | Notification/account activity utility | 01, 02 link only | W12 |
| `/kanban` | P5-04b direct replace to `/jobs?view=board`, retaining other query/hash/state | 04a, 04b | J07 |
| `/companies` | Jobs → Companies, preserve `?edit=id` | 01, 02 link only | J08 |
| `/offers` | Jobs → Offers | 01 link only | J09 |
| `/correspondence` | Correspondence primary; inbox/drafts/review | 01 link only | M01–M06 |
| `/correspondence/review` | Keep current alias to `/correspondence?view=review` | 01 regression only | M05 |
| `/profile` | Settings → Account/security; same page | 01 link only | E04–E06 |
| `/applications/:id` | Keep alias to `/jobs/:id` with search/state | 01, 08b | W01 |
| `/career` | Career Profile, current section queries | 01 link only | C01–C04 |
| `/career/builder` | CVs library unchanged | 01 link only | C05 |
| `/career/builder/:id` | Identified CV editor, gated redesign | 09–14 | C06–C12 |
| `/admin/audit` | Authorized Admin → Audit | 01 link only | A02 |
| `/admin/users` | Authorized Admin → Users | 01 link only | A01 |
| `/admin/system` | Authorized Admin → System | 01 link only | A03 |
| `/trash` | Jobs utility; deleted-only restore/edit | 01, 03 | J06 |
| `/settings` | Account → Settings; tabs unchanged | 01, 02 integration only | S03–S05, J10 |
| `/settings/connected-accounts` | Settings → Connections | 01 link only | M06, E03 |

## Query and lifetime acceptance

Use the complete [Phase 3 query/section tables](../phase-3/ROUTE_PLAN.md#query-state-and-compatibility-contract), including `q`, `status`, `companyId`, `location`, `needsFollowUp`, `readiness`, `includeDeleted`, `sortBy`, `sortDir`, `page`, capture `add`/`addtext`, `from`/`focusJobId`, `section`, `followMode`, company edit and correspondence review. Preserve unrelated safe query metadata when a view/section changes; do not carry sensitive tokens into titles/history. Unknown keys select a safe view without writes. Keep current numeric tab adapters and aliases before adding new canonical sections in P5-08b.

Current React Routes mount page owners; do not assume the Jobs component stays mounted behind a job detail. URL restores filter/page context and return state restores row focus; local selection/density lifetime must be characterized in real App, separately from a mounted component fixture. New view switching must make clearing/retaining page-scoped selection explicit. Never silently persist private list/draft state to solve navigation.

Keep `App` session-invalidated unmount outside `Application`; Toast → Theme → I18n → Confirm → Prompt → ThemeControls → Router and private AccountPlan ownership unchanged. Keep the existing router authority and auth resolution, callback origin/state handling and safe denied admin API result. Theme change must not remount dirty forms. For each migrated route test direct URL, refresh, Back/Forward, legacy query, missing/foreign object, permissions, dirty Cancel/Discard and account switch before claiming parity.