CV-Engine/README.md

# CV Engine — Developer Onboarding Guide

This guide helps new developers ramp up quickly on the CV Engine. It explains the architecture, how components work, data flow, theming, templates, and how to run and extend the project.

## Quick Start
- Prereqs: Node.js 18+ and npm.
- Client setup:
  - `cd cv-engine`
  - `npm install`
  - `npm run dev`
  - Open `http://localhost:5173/`.
- (Optional) Export server for PDF:
  - `cd cv-export-server`
  - `npm install`
  - `npm run dev`
  - Endpoint: `POST /export/pdf` (consumes CV JSON, returns PDF).

## Repository Layout
- `cv-engine/` — React + Vite app: editors, templates, preview, theming, thumbnails.
- `shared-printable/` — Shared HTML builder used by client and server.
- `cv-export-server/` — Express service that renders PDFs with Puppeteer.

## Core Concepts
- Single source of truth: CV is a JSON model validated by Zod (`cv-engine/src/schema/cvSchema.ts`).
- Inline preview renders React templates; printable preview uses a shared HTML builder for A4 output.
- Theming is applied via CSS variables so templates and thumbnails react to color selection.

## Data Model & State
- `src/schema/cvSchema.ts`
  - Fields: `personal`, `summary`, `work`, `education`, `skills`, `languages`, `certifications`, `templateId`, `colorTheme`.
  - Validation: bullets ≤160 chars, summary ≤600 chars; required fields for jobs/education.
  - Helpers: `sanitizeHtml`, `escapeText`, `createEmptyCV`.
- `src/store/cvStore.ts`
  - Holds CV data and UI state (`activeStep`, `isDirty`, save status).
  - Actions: `updatePersonal`, `addWorkItem`, `updateWorkItem`, reorder functions, section validators, `updateTemplateId`, `updateColorTheme`.
  - Selectors (via hooks): used across editors and preview to read/write state.

## App Flow & Top-Level Components
- `src/App.tsx`
  - Orchestrates the stepper and current editor panel (template, personal, work, education, skills, summary).
  - Right panel shows live preview (`PreviewPanel`). Autosaves using `useLocalAutosave`.
- `src/components/Stepper.tsx`
  - Displays steps and controls navigation.
  - Validates the current section before moving forward.
- `src/components/TemplateGallery.tsx`
  - Shows a grid of template thumbnails with filters (`ATS` vs `Visual`).
  - Clicking a card sets `templateId` in state.
- `src/components/PreviewPanel.tsx`
  - Toggle between `inline` and `printable` modes.
  - Inline: renders the selected React template via `templatesMap[templateId]` inside `ThemeProvider`.
  - Printable: builds full A4 HTML with `buildPrintableHtml(cv, templateId)` and loads it in an iframe.
  - Also includes `TemplateGallery` and export controls.
- `src/components/ThemeProvider.tsx`
  - Applies CSS variables from the selected `ColorTheme` (`getThemeCSS`) to make templates/theme-aware.
- `src/components/ExportControls.tsx`
  - Buttons to kick off export to the server, track job status, and download the result.

## Editors (data entry)
- PersonalEditor (path: `src/editors/PersonalEditor.tsx`)
  - Collects name, contact details, location, links; updates `cv.personal`.
- `src/editors/WorkEditor.tsx`
  - CRUD jobs, reorder, and manage bullets with length guidance.
  - Validates required fields (`title`, `company`, `startDate`) and prevents more than 6 bullets.
- `src/editors/EducationEditor.tsx`
  - CRUD education entries; degree, school, dates, optional notes; reorder.
- `src/editors/SkillsEditor.tsx`
  - Add skills with optional level; reorder skills; chips-style display.
- `src/editors/SummaryEditor.tsx`
  - Rich text editor (Tiptap) with bold/italic and lists, character count, and sanitization.

## Templates (inline preview)
- `src/templates/ATSTemplate.tsx`
  - ATS-friendly, serif typography, underlined section headings.
  - Sections: Header (centered), Professional Summary, Professional Experience (company, title, date range, bullets), Education, Skills, Languages.
  - Uses helpers: `escapeText`, `sanitizeHtml`, `formatDate` and CSS variables (`var(--theme-*)`).
- `src/templates/ClassicTemplate.tsx`
  - Clean, traditional layout; accent color on headings; chip-style skills.
- `src/templates/ModernTemplate.tsx`
  - Visual layout with colored header and two-column sections; optional photo.
- `src/templates/MinimalTemplate.tsx`
  - Bare, whitespace-forward layout; serif headings; simple chips for skills and languages.
- `src/templates/TimelineTemplate.tsx`
  - Visual timeline with a left sidebar for contact/skills and right-column timeline content.
- `src/templates/registry.ts`
  - Declares `templatesRegistry` and `templatesMap` (id → component, name, category, thumbnail).
  - Thumbnails can be static SVGs in `src/assets/templates` or dynamically generated.

## Thumbnails & Theming
- `src/utils/thumbnailGenerator.ts`
  - Contains `baseSVGs` with SVG blueprints per template using placeholders like `{{primary}}`, `{{text}}`, `{{background}}`.
  - Generates data URLs by replacing placeholders with the active theme palette.
  - ATS thumbnail is sectioned and theme-aware to reflect the template’s look.

## Printable HTML & Export
- Client wrapper: `src/utils/printable.ts`
  - Sanitizes summary and calls `shared-printable/buildPrintableHtml.js` to build full A4 HTML.
- Shared builder: `shared-printable/buildPrintableHtml.js`
  - Returns a complete HTML document with print-safe styles; supports multiple templates (ATS, Timeline).
- Server: `cv-export-server/server.js`
  - `POST /export/pdf` consumes CV JSON, builds HTML, renders PDF via Puppeteer, and streams it back.
  - You can later move this to a worker or serverless with proper Chromium setup.

## Theming (colors)
- `src/types/colors.ts` (referenced via imports in the app)
  - Defines `ColorTheme` and named palettes.
  - `getThemeCSS(theme)` returns CSS variables (`--theme-primary`, `--theme-secondary`, `--theme-text`, etc.) applied by `ThemeProvider`.
  - Templates and thumbnails consume these via `var(--theme-*)` or placeholder substitution.

## Typical Development Tasks
- Add a new template
  - Create `src/templates/MyTemplate.tsx` (React component accepting `{ cv }`).
  - Add a thumbnail (static SVG under `src/assets/templates` or a `baseSVGs.myTemplate` entry in `thumbnailGenerator.ts`).
  - Register in `src/templates/registry.ts` with id, name, category, and component.
  - If printable output differs significantly, add a variant to `shared-printable/buildPrintableHtml.js` keyed by `templateId`.
- Add a new field to the CV model
  - Update `cvSchema.ts` (Zod schema and default values).
  - Extend relevant editors and templates to read/write/render the field.
  - Update `buildPrintableHtml.js` if needed for print parity.
- Add a new color theme
  - Extend palettes in `types/colors.ts`.
  - The rest of the app picks up the theme via `ThemeProvider` and SVG thumbnail generator.

## Commands
- Client: `npm run dev`, `npm run build`, `npm run preview`, `npm run lint` (inside `cv-engine`).
- Server: `npm run dev`, `npm run start` (inside `cv-export-server`).

## Testing & Quality
- Unit/integration: suggested in docs (Vitest/Jest, React Testing Library).
- Visual regression: consider Percy/Chromatic for templates and printable HTML screenshots.
- E2E: Playwright covering editor flow, preview, export.
- Linting: ESLint config in `cv-engine/eslint.config.js` with TS + React rules.

## Troubleshooting
- Dev server not reachable: ensure `npm run dev` is running and check for port conflicts.
- Summary HTML issues: verify `sanitizeHtml` usage and allowed tags.
- PDF export errors: confirm the server is running; check console logs; verify Puppeteer can launch (server or CI environment may need Chromium flags).
- Template thumbnails: if colors don’t change, verify placeholders in `thumbnailGenerator.ts` and theme CSS variables are applied.

## Contribution Guidelines
- Keep changes scoped; follow existing code style.
- Maintain inline ↔ printable parity when modifying templates.
- Sanitize and validate user-provided content; avoid introducing unsafe HTML.
- Prefer small, focused PRs with clear rationale.

---
## Appendix: Original Development Guide
The original, more detailed plan and background documentation follows below for deeper context.

This guide turns the CV editor engine plan into concrete, incremental tasks you can implement. It defines scope, architecture, data model, workflows, templates, preview/export, validation, accessibility, security, performance, testing, and milestones with acceptance criteria.

## Objectives
- Deliver a fast, accessible CV builder with live preview and high-quality PDF export.
- Keep data structured and templates decoupled for ATS-friendly and visual layouts.
- Ensure printable parity between inline preview and final PDF output.

## Tech Stack
- Client: React, TailwindCSS, Zustand, TanStack Query, Tiptap (+ DOMPurify)
- Server: Node.js + Express for export, Puppeteer/Playwright for PDF rendering
- Validation: Zod (or Yup)
- Testing: Vitest/Jest, React Testing Library, Playwright for E2E

## Repo Layout (proposed)
```
src/
  components/        # UI building blocks (forms, lists, stepper)
  editors/           # Step editors (Heading, Work, Education, Skills, Summary)
  templates/         # Inline templates (ATS, Visual) + shared formatters
  printable/         # Printable HTML builder and styles (@page, A4)
  store/             # Zustand store, mutations and selectors
  services/          # API calls (save/load/export) and helpers
  utils/             # escapeHtml, sanitizers, validators, formatters
  hooks/             # autosave, debounced change tracking, accessibility
server/
  export/            # Express route for PDF export
tests/               # Unit, integration, E2E, visual regression
```

## Conventions
- Strictly sanitize user HTML via `DOMPurify` and escape all text in templates.
- Keep templates pure: accept CV JSON and return JSX/HTML; no side effects.
- Scope styles via CSS modules or Tailwind; avoid global leakage.
- Maintain preview ↔ printable parity using shared formatters and data.

## Data Model (Zod-style)
```ts
const CvSchema = z.object({
  personal: z.object({
    firstName: z.string().min(1),
    lastName: z.string().min(1),
    email: z.string().email(),
    phone: z.string().optional(),
    street: z.string().optional(),
    city: z.string().optional(),
    country: z.string().optional(),
    postcode: z.string().optional(),
    links: z.array(z.object({ label: z.string(), url: z.string().url() })).optional(),
    extras: z.array(z.string()).optional(), // e.g., LinkedIn, Website, Driving licence
  }),
  summary: z.string().max(600).optional(),
  work: z.array(z.object({
    id: z.string(),
    title: z.string().min(1),
    company: z.string().min(1),
    location: z.string().optional(),
    startDate: z.string(), // ISO or YYYY-MM
    endDate: z.string().optional(),
    bullets: z.array(z.string().max(160)).max(6),
    employmentType: z.enum(['full_time','part_time','contract','intern','freelance']).optional(),
  })),
  education: z.array(z.object({
    id: z.string(),
    degree: z.string().min(1),
    school: z.string().min(1),
    startDate: z.string(),
    endDate: z.string().optional(),
    notes: z.string().optional(),
  })),
  skills: z.array(z.object({ name: z.string(), level: z.enum(['Beginner','Intermediate','Advanced']).optional() })),
  languages: z.array(z.object({ name: z.string(), level: z.enum(['Basic','Conversational','Fluent','Native']) })).optional(),
  certifications: z.array(z.object({ name: z.string(), issuer: z.string().optional(), date: z.string().optional() })).optional(),
  templateId: z.string().default('ats'),
});
```

Validation rules
- Required: `firstName`, `lastName`, `email`; at least one of `work` or `education`.
- Bullets: 1–6 per role; each ≤160 chars; avoid trailing punctuation.
- Summary: ≤600 chars; discourage emojis; sanitize on save/render.
- Links: normalize to `https://`; restrict protocols to `http`, `https`.

## Editor Flow
- Stepper: Heading → Work → Education → Skills → Summary → Finalize
- Each step runs field validation on blur and pre-navigation; critical errors block Next (e.g., invalid email).
- Drag-and-drop reorder for Work and Skills; inline error messages with `aria-describedby`.

## Template System
- Template API: `{ id, name, renderer(cv), thumbnail? }`
- Shared formatters: `formatDate`, `formatLocation`, `escapeText`, `sanitizeHtml`.
- Templates
  - ATS: semantic lists, neutral styles, no sidebars, simple typographic accents.
  - Visual: sidebar contact, accented headings, subtle color blocks (similar to sample CV).

## Inline Preview
- Render chosen template directly from CV JSON; debounce heavy updates.
- Memoize template components; isolate styles via Tailwind scopes or modules.

## Printable Preview (Iframe)
- `buildPrintableHtml(cv)` returns a complete HTML document:
  - `<html>` with embedded CSS: `@page { size: A4; margin: 18mm }` and print-safe font stack.
  - No external scripts; all assets inline; background printing enabled.
- Load via `iframe srcDoc`; maintain parity with inline by sharing formatters and sanitized summary.

## Export Service
- Express `POST /export/pdf`
  - Input: CV JSON (validated on server)
  - Compose: `buildPrintableHtml(cv)`
  - Render: Puppeteer `page.setContent(html, { waitUntil: 'networkidle0' })`, `page.pdf({ format: 'A4', printBackground: true })`
  - Output: `application/pdf` stream with filename `cv-<lastName>-<YYYYMMDD>.pdf`
- Client: Export button calls endpoint; stream download; show progress & errors.

## Persistence & Autosave
- Autosave: debounce 1–2s after idle; mark dirty while saving; show last-saved timestamp.
- API
  - `GET /cv/:id` → load draft
  - `PUT /cv/:id` → save draft
  - `POST /export/pdf` → export
- Store integration via TanStack Query mutations and selectors in Zustand.

## Accessibility
- Labels with `htmlFor`; inputs with `aria-describedby` for errors; ensure WCAG AA contrast.
- Keyboard navigation for stepper and list CRUD; focus management after add/delete.
- Templates use semantic elements: `header`, `section`, `ul`, avoiding purely presentational markup.

## Security
- Sanitize summary on input and before render; escape all template-bound text.
- Restrict allowed URL protocols; validate `mailto:` only for email display links (never user-provided).
- No inline scripts; printable builder is self-contained HTML/CSS.

## Performance
- Debounce preview/autosave; throttle rapid list operations.
- Lazy-load noncritical components (template gallery); memoize heavy subtrees.
- Avoid large assets; prefer CSS accents; keep DOM size lean.

## Testing Strategy
- Unit
  - `escapeHtml`, `sanitizeHtml`, formatters, Zod validators, store selectors
- Integration
  - Inline ↔ printable parity across templates
  - Autosave flows and error handling
  - Export success/failure
- E2E (Playwright)
  - Create CV → navigate steps → validate errors → switch templates → preview → export PDF
- Visual Regression
  - Printable HTML screenshots per template and key data permutations

## Error Handling
- Centralized error boundary; step-level error summaries; non-blocking for non-critical issues.
- Graceful server errors with retry; maintain local draft if save/export fails.

## Milestones & Tasks

### M1 — Foundations
Tasks
- Initialize client app and Tailwind; set up routing.
- Create `CvSchema`, types, and helpers (normalization, IDs).
- Implement Zustand store: CV draft, active step, templateId, UI flags.
- Build Stepper and Heading editor form with validation.
- Implement ATS inline template and preview panel.
Acceptance
- User can enter heading details with inline validation and see preview update.
- Data stored in Zustand; template renders from CV JSON.

### M2 — Content Steps
Tasks
- Work editor: CRUD, reorder, bullet editor with length guidance.
- Education editor: CRUD; reuse shared list components.
- Skills editor: tag input + quick-add chips; optional level.
Acceptance
- Add/update/delete/reorder across steps; errors appear in-place; preview updates live.

### M3 — Summary & Printable
Tasks
- Integrate Tiptap (StarterKit + Placeholder); toolbar with basic marks.
- Sanitize output; store HTML + optional JSON.
- Implement `buildPrintableHtml(cv)` and iframe preview with A4 styles.
Acceptance
- Printable preview matches inline layout (content, spacing, formatting); summary sanitized.

### M4 — Persistence
Tasks
- Wire autosave with debounced mutations; load on mount.
- Add last-saved timestamp and dirty state.
- Handle save/load errors gracefully.
Acceptance
- Draft persists across reloads; autosave feels responsive and safe.

### M5 — Export
Tasks
- Server: Express route for `POST /export/pdf` using Puppeteer.
- Client: Export button; download with progress; error UI.
Acceptance
- PDF export produces a visually faithful A4 document with correct filename.

### M6 — Templates
Tasks
- Add Visual template; gallery picker with thumbnails and filters (ATS vs Visual).
- Persist `templateId`; ensure both inline and printable support switching.
Acceptance
- Users switch templates instantly; parity holds across preview and PDF.

### M7 — QA & Polish
Tasks
- Accessibility pass; performance tuning; code cleanup.
- Unit, integration, E2E, visual tests; CI workflow.
Acceptance
- Tests green; meets accessibility and performance targets.

### M8 — Enhancements (optional)
Tasks
- Import structured CV (JSON); version history; i18n; AI assist.
Acceptance
- Optional features are behind flags and do not regress core flows.

## Setup (placeholder)
Commands to run once you scaffold the app:
```
npm create vite@latest cv-engine -- --template react-ts
cd cv-engine
npm i tailwindcss @tiptap/react @tiptap/starter-kit dompurify zustand @tanstack/react-query zod puppeteer express
npx tailwindcss init -p
```
Adapt paths to your chosen structure. This repo currently contains planning documents only.

## Acceptance Criteria Checklist (global)
- Structured CV JSON validated end-to-end
- Live inline preview with ATS template by M1
- Printable HTML parity by M3 (layout, spacing, typography, sanitization)
- Autosave with clear feedback by M4
- Reliable PDF export by M5
- At least two templates with instant switching by M6
- Accessibility AA and test coverage by M7

## User Journey
- User starts by selecting a template from the gallery.
- They then navigate through the stepper to fill out their personal information, work experience, education, skills, and summary.
- Photo upload should only show if the selected template has a placeholder for a profile photo.
- After completing the steps, they can preview their CV in real-time with the selected template.
- If they are satisfied with the preview, they can export their CV as a PDF file.

## Glossary
- ATS: Applicant Tracking System; favors semantic, minimal styling.
- Parity: Inline preview and exported PDF display equivalent content/layout.
- Printable builder: Function that returns a self-contained HTML document for PDF rendering.

---
Use this README as the source of truth during implementation. Update sections as architecture evolves, but keep template parity, sanitization, and accessibility as non-negotiable constraints.