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.

**Delivered 2026-07-20 (increment 2 — COMPLETED):**

*Sections extracted* into `src/views/career/CareerProfileSections.tsx` (one file, one component per
export), plus `FieldReviewNote` + `confidenceTone` moved there verbatim and shared with the parent:

| Component | Slice | Props |
|---|---|---|
| `PersonalInformationSection` | `contact` | `value`, `onChange`, `getMetadata` |
| `ProfessionalSummarySection` | `summary` | `value`, `onChange`, `getMetadata` |
| `SkillsSection` | `skills` | `value`, `onChange`, `getMetadata` |
| `InterestsSection` | `interests` | `value`, `onChange`, `getMetadata` |
| `LanguagesSection` | `languages` | `value`, `onChange`, `getMetadata` |
| `WorkExperienceSection` | `jobs` | `value`, `onChange` |
| `EducationSection` | `education` | `value`, `onChange` |
| `OtherSectionsSection` | `otherSections` | `value`, `onChange` |

Each section is presentational: it receives its slice + `onChange(next)`; the parent still holds
`structuredCv`, loads, saves, and owns every extraction/import action. `getMetadata` is a callback
(`getStructuredCvFieldMetadata` over the whole profile) so sections stay decoupled from the full shape.
No section makes an API call. `CareerProfilePage` dropped from 1376 → ~1200 lines.

**No `ProjectsSection` / `CertificationsSection` were created** — the editor never had those sections
(`StructuredCvProfile` has no editable projects/certifications UI here; such content lives in "Other
sections"). Inventing them would add functionality, which this refactor explicitly avoids. Flagged for
a product decision in a later phase.

*Duplicate concepts hidden* (not deleted) behind an **"Advanced CV tools"** toggle on the Career
Profile page, collapsed by default:
- **CV Structure Overview** ("Profile sections" parse block)
- **Template-driven CV Builder** (rewrite templates + PDF carousel)

Both stay mounted and fully functional — gated with `display: none` via `showAdvancedCvTools`, so the
underlying flows (and their tests) are intact and reachable, just out of the default workflow. The
real CV Builder at `/career/builder` is the single CV-generation surface.

*Tests* (all green): existing profile-page tests re-pointed to reveal advanced tools before touching
those controls; added "editing a field in an extracted section updates parent state and flows into
save" (proves render → edit → `PUT /career/profile { profile, cvText }`). The save-invariant test from
increment 1 still pins the exact payload.

*Verified:* tsc clean, production build clean, **137 frontend tests pass**. No API, save-payload,
extraction, or data-model change.

**Future removal plan (later phase, not now):** once Phase 2 (Import CV review) and the real CV
Builder cover every flow the hidden blocks serve, delete the structure-overview parse block and the
template-driven builder from `CareerProfilePage` entirely, and drop the `showAdvancedCvTools` toggle.
Until then they remain behind the toggle so no tested functionality is lost.

**Still open for Phase 1 polish (optional, low priority):** a dedicated `CareerProfileHeader`
component and per-section actionable empty-state copy ("No work experience added yet" → the Add button
already present). Neither is blocking; both are cosmetic.

### Phase 2 — Import CV review screen (DONE 2026-07-30)
Extraction runs now stop at `pending_review`; they no longer overwrite the career profile. A backend diff
and conservative merge preserve curated/unmatched data, stable item IDs and non-empty values. The
Career Profile shows additions/updates by category with Apply/Discard actions. Low-confidence changes
have stable change IDs, are excluded by default in the API, and require individual checkbox confirmation.
Projects, certifications, languages-from-prose, grouped skill prefixes, glued date/title text, common
mojibake, and nested earlier/part-time roles are covered by regression tests. Part-time roles are separate
experience entries. No schema migration was required; pending profiles already fit `CvExtractionRun`.

### Phase 3 — Remove the second CV builder (DONE 2026-07-30)
The hidden template/rewrite/PDF-carousel block and all of its state, helpers, saved-job fetch, preview
dialog, and obsolete tests were deleted from `CareerProfilePage`. Career Profile now links directly to
`/career/builder`, the single owner of templates, layout, variants, previews and PDF generation. The
raw import section parser remains under Advanced CV tools as a recovery path.

### Phase 4 — WYSIWYG for long-form fields (DONE 2026-07-30)
Reused the existing dependency-free Markdown toolbar for the professional summary, work and education details, custom/project sections, and cover letters. Native textarea undo/redo remains available and stored payloads remain clean strings/string arrays.

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.