# 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 ```text Template ↓ Mutate Page 2 ↓ Generate PDF ``` the runtime shall become ```text 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 ```text 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 ```ts 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 ```text 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 ```ts 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 1. PageRole 2. Section Builder 3. Marker Rule 4. 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.