PSA/ee/docs/plans/2026-03-31-pdf-generation-consolidation/SCRATCHPAD.md

Scratchpad: PDF Generation Consolidation

Key Discoveries

Current State (uncommitted on fix/designer_image_support)

• packages/billing/src/services/pdfGenerationService.ts — already consolidated into a single PDFGenerationService class handling invoices, quotes, and documents
• packages/billing/src/services/quotePdfGenerationService.ts — deleted; deprecated alias createQuotePDFGenerationService points to createPDFGenerationService
• server/src/services/pdf-generation.service.ts — deleted; was the original invoice/document PDF service living in the server package

What Was Already Unified

• Single generatePDFBuffer() (Puppeteer orchestration) — no more duplication
• Single generateAndStore() — handles invoice, quote, document via discriminated options
• Single generatePDF() — dispatches to getInvoiceHtml, getQuoteHtml, getDocumentHtml
• renderQuotePreview() — lives on PDFGenerationService alongside invoice methods
• Workflow event publishing happens for all source types in generateAndStore()

Shared Infrastructure (unchanged)

• renderInvoiceTemplateAstHtmlDocument() in server-render.ts — used by both invoice and quote paths
• evaluateInvoiceTemplateAst() — evaluator is type-agnostic despite "invoice" naming
• renderEvaluatedInvoiceTemplateAst() — React renderer, also type-agnostic
• resolveInvoicePdfPrintOptionsFromAst() — print settings from AST
• browserPoolService — singleton browser pool
• Image inlining via inlineDocumentImages() in server-render.ts — converts /api/documents/view/{fileId} to base64 data URIs for Puppeteer

Committed Work (on branch, 1 commit 6523c096)

• workspaceAst.ts: Image node import/export preserves AST expressions (src/alt) with change detection
• server-render.ts: Added <base href> tag using NEXTAUTH_URL for relative URL resolution in Puppeteer

Key File Paths

• Consolidated service: packages/billing/src/services/pdfGenerationService.ts
• Service exports: packages/billing/src/services/index.ts
• Server render: packages/billing/src/lib/invoice-template-ast/server-render.ts
• React renderer: packages/billing/src/lib/invoice-template-ast/react-renderer.tsx
• Evaluator: packages/billing/src/lib/invoice-template-ast/evaluator.ts
• Print settings: packages/billing/src/lib/invoice-template-ast/printSettings.ts
• Invoice adapters: packages/billing/src/lib/adapters/invoiceAdapters.ts
• Quote adapters: packages/billing/src/lib/adapters/quoteAdapters.ts
• Quote template selection: packages/billing/src/lib/quote-template-ast/templateSelection.ts
• Quote bindings: packages/billing/src/lib/quote-template-ast/bindings.ts
• Quote standard templates: packages/billing/src/lib/quote-template-ast/standardTemplates.ts

Callers of PDF Generation

• server/src/lib/api/services/InvoiceService.ts — imports PDFGenerationService, createPDFGenerationService
• server/src/lib/jobs/handlers/invoiceEmailHandler.ts — imports PDFGenerationService, createPDFGenerationService
• server/src/lib/jobs/handlers/invoiceZipHandler.ts — imports PDFGenerationService, createPDFGenerationService
• packages/billing/src/actions/quoteActions.ts — imports createPDFGenerationService
• packages/billing/src/actions/invoiceJobActions.ts — imports createPDFGenerationService
• packages/client-portal/src/actions/client-portal-actions/client-billing.ts — imports from billing services

Tests

• packages/billing/src/actions/invoicePdfGenerationAstWiring.test.ts — source-code wiring assertions (checks imports exist)
• server/src/services/pdf-generation.service.printSettings.test.ts — print settings tests, updated mocks to point at @alga-psa/billing paths
• packages/billing/tests/quote/quotePdfGenerationService.test.ts — quote PDF generation tests
• packages/billing/src/services/pdfGenerationService.printSettings.test.ts — exists (check if new or moved)

Decisions

• (2026-03-31) Consolidation approach: single class with internal dispatch rather than base class + subclasses. Simpler, avoids inheritance complexity.
• (2026-03-31) Workflow events fire for all source types (invoice, quote, document) — previously only invoices published DOCUMENT_GENERATED.
• (2026-03-31) Deprecated aliases (createQuotePDFGenerationService, QuotePDFGenerationService type) kept for backward compat during transition.

Remaining Work

1. Verify all callers compile and work with consolidated service
2. Ensure server/src/services/pdf-generation.service.ts deletion doesn't break any remaining imports
3. Update/migrate tests that referenced old service paths
4. Consider adding renderInvoicePreview() method (parity with quote preview)
5. Consider renaming "Invoice" in shared AST types to be entity-agnostic (follow-up)