5.7 KiB
Task P.4.2 - PDF Runtime Architecture & Section-based Rendering Design
Objective
Design the next-generation PDF runtime architecture for the CRM document system.
The new runtime must support:
- Dynamic page insertion
- Section-based document composition
- Optional document sections
- Future extensibility
- Full backward compatibility
This is an architecture task only.
Do NOT modify production code.
Do NOT modify template JSON.
Do NOT modify database schema.
Inputs
Reuse verified findings from
- Task P.4 Discovery
- Task P.4.1 Runtime Verification
Do not repeat discovery.
Design Principles
The runtime must become
- page-role driven
- section-based
- version compatible
- renderer independent
- extensible
Business logic must not depend on page indexes.
Core Architecture
The runtime shall assemble a document from independent sections.
Instead of
Template
↓
Mutate Page 2
↓
Generate PDF
the runtime shall become
Quotation Document Data
↓
Template Resolver
↓
Mapping Resolver
↓
Compatibility Adapter
↓
Page Resolver
↓
Section Composer
↓
Template Assembler
↓
PDF Generator
Section-based Rendering
Introduce the concept of
Document Sections.
Examples
- Customer
- Product Items
- Topics
- Conditions
- Signature
- Attachments
- Appendix
- Warranty
- Cover
A section represents logical document content rather than physical pages.
A section may generate
- zero pages
- one page
- multiple pages
Optional Sections
The runtime must support optional sections.
A section may be
- Required
- Optional
The runtime shall be capable of skipping optional sections without requiring another template version.
Examples
Customer
Required
Product Items
Optional
Topics
Optional
Conditions
Optional
Signature
Required
This capability is architectural only.
No UI configuration is required in this task.
Render Policy
Design a Render Policy abstraction.
Example
interface RenderPolicy {
section: PageRole;
enabled: boolean;
required: boolean;
visibleWhenEmpty: boolean;
}
The runtime shall evaluate Render Policy before rendering each section.
The policy source is intentionally undefined in this task.
Future tasks may provide it from
- user selection
- customer preference
- template defaults
- organization defaults
Runtime Pipeline
Design
Document Data
↓
Template Resolver
↓
Mapping Resolver
↓
Compatibility Adapter
↓
Page Resolver
↓
Render Policy Resolver
↓
Section Composer
↓
Customer Section
↓
Product Item Section
↓
Topic Section
↓
Condition Section
↓
Signature Section
↓
Template Assembler
↓
PDF Generator
Describe every stage.
Runtime Components
Design responsibilities for
- Template Resolver
- Mapping Resolver
- Compatibility Adapter
- Page Resolver
- Render Policy Resolver
- Customer Section Builder
- Product Item Engine
- Topic Engine
- Condition Engine
- Signature Resolver
- Template Assembler
- PDF Render Gateway
Each component must have a single responsibility.
Page Marker Strategy
Design page discovery using logical markers instead of indexes.
Support
- explicit page markers
- legacy inference
- fallback detection
The runtime must never rely on
schemas[1]
Runtime Contracts
Define contracts for
- ResolvedTemplate
- ResolvedPages
- RenderPolicy
- BuiltSection
- RuntimeIssue
- AssembledTemplate
Document ownership and responsibilities.
Compatibility Strategy
Support
- legacy templates
- future templates
without duplicating runtime logic.
Legacy templates shall work through the Compatibility Adapter.
Future Extensibility
The architecture shall allow adding new document sections without changing existing section builders.
Examples
- Drawing
- Specification
- Gallery
- Warranty
- Appendix
- Inspection Report
A new section should require only
- PageRole
- Section Builder
- Marker Rule
- Assembly Rule
Error Handling
Design behavior for
- missing marker
- duplicate marker
- missing mappings
- empty optional section
- empty required section
- invalid template
Runtime shall fail gracefully and accumulate Runtime Issues.
Migration Strategy
Design migration from
Current Runtime
↓
Section-based Runtime
without breaking
- Preview
- Download
- Approved PDF
- Existing Template Versions
No database migration.
No API changes.
Sequence Diagrams
Produce
- Current Runtime
- Proposed Runtime
including
- Render Policy
- Section Composition
Component Diagram
Include
- Template Resolver
- Compatibility Adapter
- Page Resolver
- Render Policy Resolver
- Section Composer
- Section Builders
- Template Assembler
- PDF Generator
Implementation Roadmap
Split implementation into phases.
Example
Phase 1
Runtime Contracts
Phase 2
Compatibility Adapter
Phase 3
Page Resolver
Phase 4
Section Composer
Phase 5
Product Item Engine
Phase 6
Template Upgrade
Phase 7
Regression Tests
Each phase must be independently testable.
Constraints
- Architecture only.
- No production implementation.
- No template modification.
- No database changes.
- No API changes.
Acceptance Criteria
- Runtime is section-based rather than page-index-based.
- Optional sections are supported by design.
- Product Item pages are independent from Topic pages.
- Existing template versions remain compatible.
- Future document sections can be added without redesigning the runtime.
- Template Version is used only for structural/layout differences, not for enabling or disabling document sections.
- The design is ready for implementation in Task P.4.3 with minimal architectural decisions remaining.