jobtrackingapp/docs/career-workspace-ux-refactor.md

Career Workspace + CV Builder UX refactor

2026-07-20. UX/product restructuring against v1.0.0. Frontend-only — no change to CareerProfiles, CvVariants, the CV generation pipeline, extraction APIs, AI services, permissions, or tenant isolation.

This document is the plan. It is delivered staged: Phase 0 (the sidebar bug and the framing copy) is implemented and tested now; Phases 1–4 are scoped for incremental delivery because they require surgery on the 1376-line CareerProfilePage and touch the production CV/extraction flow, where a single large rewrite would risk the "do not break" list. Each later phase is independently shippable and verifiable.

Current problems

1. Sidebar double-highlight. On /career/builder/{id}, both "Career Workspace" and "CV Builder" light up. Root cause: AppShell used pathname === to || pathname.startsWith(to + "/") per item, so /career matched every /career/... child. No "most specific wins" rule. (Fixed — Phase 0.)
2. Too many competing concepts on one page. CareerWorkspacePage is a thin shell around CareerProfilePage (1376 lines), which bundles: a structured-CV editor, extraction-run history, a "CV structure overview", rewrite templates with a PDF carousel (a second, template-driven CV builder), and field-level review metadata. A user cannot tell which artifact is "their CV".
3. Internal vocabulary leaks to users — "structured CV", "JSON structure", "extraction schema", "structure overview". These are implementation concepts.
4. Extraction is opaque. Upload runs, the profile changes, but the user never sees what changed and cannot approve it. History is shown as a primary section instead of the result of an import.
5. Two CV builders. The template-driven rewrite/PDF flow inside the profile page overlaps the real CV Builder (/career/builder), which already owns templates, layout, styling, variants and PDF.

New information architecture

Product rule: Career Profile holds your information; CV Builder creates documents from it.

Surface	Owns	Does NOT own
Career Profile (/career)	Personal info, professional summary, work experience, education, skills, projects, certifications, languages. The facts.	Templates, layout, styling, PDF, variants
CV Builder (/career/builder, /career/builder/{id})	Templates, layout, styling, section order/visibility, variants, PDF generation	Career facts (it reads the profile)

Career Profile page structure (target):

• Header — "Career Profile", subtitle "This information powers your CVs, applications, cover letters and AI assistance.", profile completeness %, last updated, quick action → CV Builder.
• Sections (user-facing labels only): Personal information · Professional summary · Work experience · Education · Skills · Projects · Certifications · Languages.
• Import CV — current source (filename, date, status) + [Upload new CV]; after extraction a review screen (below). History moves to Settings → Advanced → Import history.

Removed / relocated concepts

Concept	Disposition
"Structured CV Editor"	Renamed and reframed to Career Profile editor (same fields, user vocabulary)
"CV Structure Overview"	Removed from the user surface; if needed for debugging, move under admin/developer tools
"Template-driven CV Builder" (rewrite templates + PDF carousel inside the profile page)	Removed — the CV Builder already provides templates, layouts, styling, sections, customization and PDF. One CV Builder only
Extraction run history as a primary section	Relocated to Settings → Advanced → Import history
Internal terms ("structured CV", "JSON", "schema") in labels/help text	Replaced with plain language

Route ownership (authoritative)

/career                 → Career Profile        (Career Workspace nav item)
/career/builder         → CV Builder            (CV Builder nav item)
/career/builder/{id}    → CV Builder            (child of CV Builder, NOT Career Profile)

Rule: the sidebar item whose to is the longest prefix the current path is at or under wins; all others are inactive. A child route never activates a parent nav item.

Implementation plan

Phase 0 — Sidebar bug + framing (DONE, this change)

• AppShell.activeNavTo(pathname, tos) — exported pure function; longest-owning to wins. selected now compares against the single computed activeTo across both nav lists.
• Breadcrumb/title in App.tsx: explicit /career/builder → "CV Builder" ownership before the /career fallback (previously /career/builder showed "Career Workspace").
• Career Workspace header reframed to the "Career Profile" product framing.
• Tests: sidebar-active-nav.test.ts — asserts exactly one active item for /career, /career/builder, /career/builder/{id}, and that no item double-highlights.

Phase 1 — Career Profile editor sections (frontend)

Reorganise CareerProfilePage presentation into the eight named sections with user-facing labels; strip internal vocabulary from headings/help. No data-model or API change — the same StructuredCvProfile shape is read and saved. Ship behind the existing page; verify save/load of each section against the existing profile API.

Phase 2 — Import CV review screen

Add a post-upload "New information found" review (Experience / Skills / Languages / Education) with [Accept all] · [Review individually] · [Discard], diffing the extracted profile against the current one client-side (no backend change — the extraction API already returns the structured result and field metadata). Nothing is written until the user accepts. Relocate run history to Settings → Advanced → Import history.

Phase 3 — Remove the second CV builder

Delete the rewrite-template + PDF-carousel flow from CareerProfilePage. Confirm the CV Builder (/career/builder) covers templates/layout/styling/variants/PDF first (it does). Verify public CV and PDF generation still work end to end.

Phase 4 — WYSIWYG for long-form fields

Rich editor (bold, lists, links, undo/redo) for professional summary, work descriptions, achievements, projects, cover letters. Store clean HTML or Markdown only — no editor-specific state — and the renderer consumes the same format. Choose a small dependency already compatible with the stack, or a minimal contentEditable wrapper; decide at Phase 4 to avoid a premature dependency.

Preserved (verified not touched)

CareerProfiles, CvVariants, CV generation, public CV pages, extraction APIs, AI services, permissions, tenant isolation. Phases 1–4 are frontend-only; any that appears to need a backend change is a signal to re-scope, not to change the model.

Why staged

The removals and the review/WYSIWYG surfaces all require editing the 1376-line CareerProfilePage and the live extraction/generation path. Delivering them as one change would put the v1.0.0 CV pipeline at risk with no incremental verification. Each phase above is small enough to ship and verify on its own.