docs/apply-recommendations-implementation.md

# Apply Recommendations Implementation Note

What was implemented

Pulse CV now includes a post-analysis Apply recommendations workflow that appears only after a completed analysis and only when an original CV source file is available.

The workflow includes:

• Apply recommendations action in the Analyzer results screen
• edit-plan preview before file generation
• updated CV generation in the same input format
• downloadable change report / redline summary
• DOCX-first surgical editing path
• transparent PDF fallback path

Files added

• server/cvApply/types.ts
• server/cvApply/editPlan.ts
• server/cvApply/storage.ts
• server/cvApply/pythonWorker.ts
• scripts/cv_apply_worker.py
• requirements-doc-worker.txt

Files updated

• server.ts
• src/App.tsx
• Dockerfile

Chosen libraries

DOCX editing

• python-docx

Why:

• strongest practical choice in the current stack for paragraph-aware DOCX editing
• allows targeted paragraph replacement / insertion
• preserves much more styling and section structure than full regeneration

PDF generation fallback

• reportlab

Why:

• reliable recruiter-safe regenerated PDF output
• honest fallback when exact layout-preserving PDF editing is not realistic

Why DOCX and PDF paths differ

DOCX is structurally editable and supports a true surgical patch path. PDF is not a reliable semantic editing format for exact high-fidelity rewriting across arbitrary source files.

Therefore:

• DOCX input -> DOCX output with high-fidelity targeted edits
• PDF input -> PDF output in recruiter-safe fallback mode when exact layout preservation cannot be guaranteed

Fidelity guarantees

DOCX

Reasonable guarantees:

• preserve paragraph order
• preserve headings and section flow
• preserve most paragraph styling where possible
• preserve contact details and chronology
• patch only targeted sections when possible

PDF

Honest guarantee:

• preserve content intent and same output format
• generate recruiter-readable / ATS-readable PDF
• do not guarantee exact original visual layout for arbitrary PDFs

Safety rules enforced

• no invented tools, degrees, titles, achievements, or experience
• dates and chronology are preserved unless intentionally edited
• recommendations are applied only through Pulse CV analysis output
• AI is not used as the source of truth for scoring or fit logic
• only FinalCvPatch.replacementText may enter DOCX generation
• DisplayRecommendation.message is UI-only and can never be written into the CV
• multilingual meta-language validation runs before patch creation and again inside the DOCX worker
• if a generated patch contains advice, conditional wording, UI labels, or language mismatch, the download is blocked

Multilingual repair architecture

Pulse CV now separates:

• DisplayRecommendation
• InternalEditInstruction
• FinalCvPatch

The core product rule is:

Analyze in any language.
Recommend in the UI layer.
Patch only in the CV language.
Patch only with evidence.
Never write advice into the CV.

Implemented API

• POST /api/cv/apply-recommendations/plan
• POST /api/cv/apply-recommendations/generate
• GET /api/cv/generation/:jobId/status
• GET /api/cv/generation/:jobId/download
• GET /api/cv/generation/:jobId/redline

Validation completed

• local lint passed
• local build passed
• Python worker compilation passed
• DOCX end-to-end generation passed
• PDF end-to-end fallback generation passed

Current limitations

• DOCX is the happy path and the strongest implementation today
• PDF output is intentionally transparent fallback, not fake exact-layout editing
• server orchestration still lives partly in server.ts and can be modularized further later