jobtrackingapp/docs/architecture/cv-builder.md

CV Builder (Career Workspace Builder)

Phase 4 (2026-07-18). The builder that turns the master career profile into themed, exportable, optionally-public CVs. Companion to docs/architecture/cv-theme-engine.md, docs/architecture/career-profile-model.md, and MASTER_IMPLEMENTATION_GUIDE.md. Verified against code and a running container.

Source-of-truth chain

CareerProfile (the only editable career source)
   ↓ read (never copied)
CvVariant       — a LENS: section order/visibility, per-item overrides, theme + builder settings
   ↓ resolve
CvRenderModel   — presentation projection (CvVariantResolver)
   ↓ render (one path, theme = data)
HTML            — ThemedCvRenderer
   ↓ export / share
PDF  |  Public CV (/cv/{slug})

The master profile is never written by the builder. A variant references career items by their stable ItemKey; overriding a bullet stores the override on the variant, leaving the profile untouched (CvBuilderTests.Resolver_applies_item_override_bullets_without_touching_the_master).

Variant model

CvVariant (Models/CvVariant.cs) + CvVariantVersion (autosave history). The whole lens lives in one SettingsJson blob (CvVariantSettings, Models/CvVariantSettings.cs) because it is edited and saved as a unit — never queried field-by-field. A variant stores:

• ThemeId + overrides: accent, heading/body font, density, page size, photo/icons/page-numbers.
• Sections: ordered list with per-section Hidden + optional renamed Title.
• Overrides: keyed by ItemKey → { Hidden, Title, Subtitle, Bullets } (per-item, job-specific).
• CustomSections: variant-only sections not in the master profile.

PublicSlug (unguessable, globally unique) backs the public URL. IsPublic is off by default.

Rendering pipeline

1. CvVariantResolver.Build(profile, settings, fallbackName, photoDataUrl) → CvRenderModel. Applies order, visibility, item overrides and custom sections. Pure projection, owns nothing.
2. ThemedCvRenderer.Render(model, theme, settings) → HTML. One render path; the theme (data) drives layout/palette/typography/spacing. See cv-theme-engine.md.
3. PlaywrightCvPdfExporter (reused unchanged) turns the HTML into a PDF.

API

Authenticated (/api/cv, CvVariantController): GET themes; GET/POST variants; GET/PUT/DELETE variants/{id}; POST variants/{id}/duplicate; PUT variants/{id}/public; GET variants/{id}/versions, POST …/versions/{v}/restore; GET variants/{id}/preview and POST preview (live preview of unsaved settings); POST variants/{id}/export-pdf; POST ai/assist.

Anonymous (/api/public-cv/{slug}, PublicCvController): serves a public variant read-only, X-Robots-Tag: noindex. Loads the owner's profile via LoadStructuredForOwnerAsync (bypasses the tenant filter — there is no current user). Unknown/private slug → 404 (CvBuilderTests.Private_variant_is_not_served_publicly).

Builder workflow (frontend)

/career/builder lists variants (CvBuilderPage); the editor (CvBuilderEditor) is three tabs — Content, Customize, AI Tools (plus History) — beside an always-on live preview that re-renders through POST /api/cv/preview on a 350 ms debounce. Edits autosave on an 800 ms debounce (source: autosave), appending a version each save. /cv/:slug (PublicCvPage) renders a public CV in a sandboxed iframe.

AI

POST /api/cv/ai/assist reuses the existing ISummarizerService provider abstraction. It returns a suggestion the user copies in themselves — it never mutates the profile or the variant. Every prompt carries "preserve every factual claim — never invent" (MASTER_IMPLEMENTATION_GUIDE AI philosophy).

Extension points

• New theme: append a CvTheme to the catalog (cv-theme-engine.md). No renderer change.
• New section kind: add a builder in CvVariantResolver + a Kind branch in ThemedCvRenderer.
• DOCX export: add an IDocxExporter consuming the same CvRenderModel; the model is format-neutral.
• Rich text / page numbers: see cv-theme-engine.md "Deliberately not here (yet)".

Known limitation

Direct external loads of any deep link (including /cv/{slug}) currently bounce to the app root — the CSR lift-and-shift Next.js static-export setup only prerenders /, so a hard navigation to a deep path doesn't reach the react-router route (in-app client navigation works). This affects the whole SPA, not just public CVs, but public CVs are the first feature that depends on external direct links working. Fix path: serve index.html for all non-/api paths so react-router owns routing (nginx already has try_files $uri /index.html; the redirect is client-side in the Next shell). Tracked as a follow-up — see docs/architecture/frontend.md / the Next.js migration note.