diff --git a/README.md b/README.md index 91983b6..e547984 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,150 @@ -# CV Editor Engine — Development Guide +# 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.