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. No Documents/Admin destination or expanded command catalogue is implied; earlier planning text below remains historical.

Source: current App, AppShell, Phase 3 route contract. 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, 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.