PDF Template System Documentation

Last Updated: 2026-03-24 Module: apps/backend/src/pdf/ Architecture: Hexagonal (Ports & Adapters)

---

Quick Start

1. Architecture overview: pdf-module-architecture.md — Module structure, dependency flow, port bindings, API endpoints
2. Original design spec: pdf-template-configuration-system.md — Database schema, design rationale, template resolution chain
3. Template variables: template-examples/template-variables-reference.md — Available variables per document type

Test the API

# Health check (no auth required)
curl http://localhost:4000/pdf/templates/health

# Upload a template
curl -X POST http://localhost:4000/pdf/templates/upload \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","documentType":"sale","templateFormat":"standard_a4","htmlTemplate":"<h1>{{documentNumber}}</h1>","createdBy":"user-id"}'

# Generate PDF from stored template
curl -X POST http://localhost:4000/pdf/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -o output.pdf \
  -d '{"templateId":"template-uuid","data":{"documentNumber":"INV-001"}}'

Bruno collections: api-client/flowpos/collections/pdf/

Documentation Index

Document	Purpose
pdf-module-architecture.md	Current module structure, ports, endpoints, design decisions
pdf-template-configuration-system.md	Original design spec: DB schema, upload flow, security
pdf-template-implementation-checklist.md	Historical implementation progress tracker
REDIS-BULLMQ-SETUP.md	Redis + BullMQ setup for async preview generation
template-examples/	Template variable reference and example templates

Current System Status

• Template CRUD (upload, update, delete, list, search) with audit trail
• Template resolution chain: location > business > system > file fallback
• Location-specific template configuration (per document type)
• 21 document types with dedicated use cases and transformers
• LRU template cache (100 entries)
• Puppeteer PDF generation with retry logic (3 attempts)
• Handlebars template rendering with custom helpers
• BullMQ async preview generation queue
• Full Swagger/OpenAPI documentation on all controllers
• Authentication (Firebase) + rate limiting on mutation endpoints
• Health checks and cache statistics (public endpoints)