PDF Templates

PDF generation system for creating documents from templates with mapped data fields. Supports multi-page templates, combined fields, fill-in sessions, and e-signature integration.

Source Files

Layer	Path
Schema	backend/src/db/schema.ts
Template Routes	backend/src/routes/admin/pdf-templates.ts
Field Def Routes	backend/src/routes/pdf-data-field-definitions.ts
Combined Field Routes	backend/src/routes/pdf-combined-fields.ts
Export Routes	backend/src/routes/pdf-export.ts
Session Routes	backend/src/routes/pdf-document-sessions.ts
Export Service	backend/src/services/pdf-export-service.ts
Template Service	backend/src/services/pdf-template-service.ts
Session Service	backend/src/services/pdf-session-service.ts
Combined Field Service	backend/src/services/pdf-combined-field-service.ts
Conversion Job	backend/src/lib/jobs/processors/pdf-conversion.ts
Admin Page	frontend/src/pages/admin/PdfTemplatesList.tsx
Export Page	frontend/src/pages/PdfExport.tsx
Components	frontend/src/components/pdf/ (8 files)

Database Tables

Table	Purpose
pdfTemplates	Main entity — name, description, isActive; original PDF stored via CAS fileId → Files
pdfTemplatePages	Individual pages within a template — rendered page image as CAS fileId, width/height
pdfTemplateFields	Positioned fields on a page (x, y, width, height, font, linkedDataFieldDefinitionId)
pdfCombinedFields	Composite fields that merge multiple data field definitions (global, shared across templates)
pdfDataValues	Stored field values per project (API data + manual overrides)
pdfDocumentSessions	Resumable fill-in sessions — fieldValues jsonb, temporaryFields, optional project link
pdfDataFieldDefinitions	Reusable field definitions — types api (Dataverse path), metadata, custom

PDF Generation Pipeline

1. Template design — admin uploads page backgrounds and positions fields via the template editor
2. Field mapping — each field is linked to a data source (entity field, combined field, or manual input)
3. Session creation — user starts a fill-in session, optionally linked to a project
4. Data population — mapped fields auto-fill from entity data; manual fields are filled by the user
5. Export — pdf-lib renders the final PDF with all field values overlaid on the template pages
6. Storage — generated PDF is saved as a file and linked to the source entity

E-Signature Integration

Table	Purpose
signatureRequests	Outgoing signature requests linked to a PDF document
signedDocuments	Completed signed documents returned from the signature provider
signedDocumentsMetadata	Links the original, signed, and certificate Files (three CAS file refs)

Signature workflow integrates with external e-signature services for legally binding document signing.

Other PDF Generation Paths

Not everything PDF-shaped goes through this template system:

• Site protocols (Buildings) have a dedicated pdf-lib renderer at backend/src/services/site-protocol-pdf.ts (letterhead, attendees/topics/open-points, embedded photos) — I#1988, PR#1994.
• RENEWA-issued invoices render via the billing module (billing_invoice_pdf_versions), not via PDF templates.

Frontend Components

Component	Purpose
PdfTemplateEditor	Visual editor for positioning fields on template pages
PdfFieldMapper	Map template fields to data sources
PdfPreview	Live preview of the generated PDF
PdfSessionForm	Fill-in form for manual fields during a session
PdfExportDialog	Export options and download

Relationships

PdfTemplate 1──* PdfTemplatePages 1──* PdfTemplateFields
PdfTemplate 1──* PdfDocumentSessions
PdfTemplateField *──1 PdfDataFieldDefinition
PdfCombinedField *──* PdfDataFieldDefinitions
Session *──1 Users (author)
Session ──> Files (exported PDF)

Related Pages

Documents | Files | Buildings | Projects | Admin Dashboard | Service Layer Pattern | Database Architecture