# 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.
