VaultPDF Rendering Pipeline
VaultPDF processes every template through a deterministic multi-stage rendering pipeline ensuring layout stability, visual consistency, and secure document generation, structured across 12 sequential stages from structure normalization to final PDF output.
Execution Order Matters
Stages run sequentially in the order listed. No stage is skipped, even if its input is a no-op. This guarantees consistent output regardless of template complexity.
Pipeline Phases
The 12 stages are grouped into three logical phases:
Phase 1: Template Normalization
Stages 1–4 normalize the raw template tree: adaptive nesting, empty width resolution, layout consolidation, and table sanitization.
Phase 2: Style Resolution
Stages 5–8 resolve and merge all visual rules: default style fallback, font normalization, theme merging, and theme injection.
Phase 3: Layout Safety & Rehydration
Stages 9–11 apply emergency layout guards and rehydrate dynamic headers, footers, and the default footer block.
Phase 4: Rendering & Output
Stage 12 produces the final PDF output by injecting the default footer and flushing all page content, embedded assets, and document metadata.
Stage-by-Stage Reference
Adaptive Nesting
Traverses the entire template tree and wraps bare inline elements inside the correct block-level containers. This ensures every node conforms to the expected parent-child structure before any layout calculation begins.
- Supports up to 6 levels of nesting
- Automatically selects a layout mode per level: header section, table, compact key-value, mini-table, or grouped sections
- Column Manifest: schema-driven deterministic column ordering and widths
- Volume-aware margins: tightens vertical margins when row volume is high so tables always start on page 1
Why first?
All downstream stages assume a well-nested tree. Running this first removes an entire class of edge-case bugs from every subsequent stage.
Width Normalization
Scans block and cell elements for missing or zero-value width declarations and assigns computed defaults based on context (column count, container width, grid mode). Prevents invisible columns and collapsed layout children.
Layout Conflict Resolution
Reconciles conflicting layout directives (for example, a section declared as both multi-column and grid) and promotes the most specific rule. Also strips redundant wrapper elements that add no layout value.
Table Sanitization
Validates every table element in the template: ensures header and body rows are present, fills missing cells to keep rows balanced, and removes illegal nesting. Malformed tables that cannot be repaired are replaced with a styled error placeholder.
Data integrity
Table Sanitization never drops data; it restructures around it. If a cell has content but an illegal parent, the content is preserved inside a corrected wrapper.
Default Style Fallback
Applies the document's base style sheet to every element that carries no explicit style declaration. This is the lowest-priority style pass; any property already set by the template or theme is left untouched.
Font Normalization
Resolves all font references to their embedded equivalents:
- Named system fonts → embedded subset paths
- Missing font families → configured fallback chain
- Variable font axes → static instances supported by the PDF spec
Unresolvable fonts are replaced with the tenant's default body font and a warning is logged.
Theme Style Merge
Deep-merges the active theme's style overrides on top of normalized element styles. Theme values take precedence over defaults but are overridden by explicit inline styles. The merge is non-destructive; properties not present in the theme are inherited unchanged.
Theme Injection
Injects theme-level constructs that cannot be expressed as per-element styles: page background color, watermarks, bleed marks, and global header/footer slot registrations. These are written directly into the PDF document metadata layer.
Layout Validation Passes
A safety net that runs up to six rapid re-validation passes over the fully styled tree. Each pass checks for a specific class of late-breaking inconsistency introduced by style merging (e.g., an element whose computed width now exceeds its parent). Passes stop early once the tree is fully valid.
Performance note
In practice, well-formed templates exit after pass 1 or 2. If your document consistently requires many passes, review the template for conflicting width declarations.
Header Rehydration
Replaces header slot placeholders with their resolved runtime values: page numbers, document title, generation timestamp, and any custom bindings from the JSON payload. Header content is re-measured after substitution to handle variable-length values.
Footer Rehydration
Same as the previous stage but for the footer slot. Footer rehydration runs after header rehydration because some footer bindings (e.g., total page count) depend on the final header layout being settled.
Default Footer
If no footer was registered by the template or theme, this stage injects the tenant's configured default footer. If a footer is already present, this stage is skipped. The default footer is always the last element written to the page and is never overridden by content overflow.
Smart Rules & Hierarchy Rules Engine
Control field visibility, styling, computations, and layout per hierarchy level via hierarchyRules in the template.
Per-Level Layout Control
Each of the 6 nesting levels can independently declare its layout mode (HEADER, TABLE, COMPACT-KV, MINI-TABLE, or GROUPED-SECTIONS) without affecting sibling levels.
Field Visibility Rules
Show or hide fields based on data conditions, hierarchy depth, or tenant configuration. Rules are evaluated at render time against the live JSON payload.
Computed Fields
Define expressions inside hierarchyRules to derive values like totals, formatted dates, and conditional labels without pre-processing the JSON on the caller's side.
Style Overrides per Level
Apply fonts, colors, padding, and border rules scoped to a specific hierarchy level. Level-scoped styles take precedence over theme styles but not inline styles.
{
"hierarchyRules": {
"levelStyling": {
"2": { "format": "table", "fields": ["invoiceNumber", "date"] },
"3": { "format": "table", "columnFormats": { "description": "text", "qty": "number", "total": "currency" } },
"4": { "format": "compact-kv", "indentation": 16 }
}
}
}See the Pipeline in Action
Use the VaultPDF playground to submit a template and inspect each pipeline stage's output in the debug trace.
System Architecture
A deep dive into VaultPDF's No-Egress security model and tenant-native integration.
Storage Providers
How to configure VaultPDF's storage system. Covers SharePoint setup, Azure Blob Storage setup, output routing via storage-config.json, required environment variables, and the response headers returned on each render.