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 — terminology + first component split (IN PROGRESS)

Delivered 2026-07-20 (increment 1):

Terminology → user-facing (src/i18n/translations.ts, no structural change):

Internal term (before)	User-facing (after)
"Structured CV editor"	"Career information"
"CV structure overview"	"Profile sections"
"Summary bullets"	"Professional summary"
"Core skills"	"Skills"
"Analyze sections"	"Read sections"
"Original extraction"	"Original import"
hardcoded "Master career profile"	"Career profile"
Help text de-jargoned; the "Career information" help now says *"The CV Builder uses this information
to create documents."*

Component extracted: src/views/career/ProfileCompleteness.tsx — the completeness meter + missing chips + version-history accordion, pulled out of CareerProfilePage. Display-only, props in, no state or API — the first step of the split.

No API / data / model change. The save path is untouched: api.put("/career/profile", { profile: structuredCv, cvText }). A new test (profile-page.test.tsx → "saving the career profile PUTs … unchanged (Phase 1 refactor invariant)") pins exactly that call so the remaining extraction can't silently change it. Existing profile-page tests were re-pointed to the new labels; all behavioural assertions (save, parse, field values) kept.

Verified: tsc clean, production build clean, 136 frontend tests pass (was 135; +1 invariant test). Sidebar fix from the previous task still passes.

Remaining in Phase 1 (staged, needs the app running to click-verify each section's save round-trip):

• Extract the editing sections into PersonalInformationSection … LanguagesSection components and a CareerProfileHeader, keeping structuredCv + setStructuredCv + the save handler in the parent (so behaviour stays identical). This is voluminous mechanical JSX movement through a 1376-line file.
• Hide the template-driven CV builder (rewrite templates + PDF carousel) and the structure overview parse block from the user surface. Both are tested against live extraction behaviour, so each removal must move its test coverage, not delete it — done incrementally with verification.
• Per-section actionable empty states ("No work experience added yet" → [Add experience]); the Add affordances already exist, so this is copy + wiring.

Rationale for staging: these touch the live CV/extraction test surface and are best verified by driving the authenticated UI. Increment 1 is a clean, non-regressing checkpoint per the "reviewed and verified before Phase 2" instruction.

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.