Project 4: Quote Builder & Document Generator

Build a deterministic quote rendering pipeline that converts approved quote revisions into customer-ready artifacts.

Quick Reference

Attribute Value
Difficulty Level 2 (Intermediate)
Time Estimate 1-2 weeks
Main Programming Language TypeScript (Alternatives: Python, Java)
Coolness Level Level 3
Business Potential 3. Service & Support Model
Prerequisites Projects 1-3, template literacy, lifecycle basics
Key Topics Revision control, template composition, clause routing

1. Learning Objectives

  1. Create quote revisions with immutable lineage.
  2. Render deterministic quote artifacts from canonical state.
  3. Apply jurisdiction and segment-specific clauses.
  4. Persist render metadata for auditability.

2. All Theory Needed (Per-Concept Breakdown)

Concept A: Canonical State vs Presentation

Fundamentals Quote artifacts should be generated from canonical quote data, never used as source-of-truth themselves.

Deep Dive into the concept Keep pricing and policy logic outside templates. Templates should consume precomputed values. Clause routing should be data-driven by context fields.

How this fit on projects Primary here, reused in P05-approval-workflow-orchestrator.md and P07-crm-sync-integration.md.

Definitions & key terms

  • Quote revision
  • Template version
  • Clause pack
  • Render hash

Mental model diagram

Quote Revision -> Template Resolver -> Renderer -> Artifact + Metadata

How it works

  1. Freeze quote revision.
  2. Resolve template and clause set.
  3. Render and hash output.
  4. Store artifact metadata and state transition.

Minimal concrete example

Q-2026-0102-R3 + template_v7 + clause_us_v4 -> PDF + hash 93f1...

Common misconceptions

  • “PDF can be edited after send without new revision.” Should be prohibited.

Check-your-understanding questions

  1. Why separate template logic from price logic?
  2. Why version clause packs?

Check-your-understanding answers

  1. To avoid hidden arithmetic drift.
  2. To preserve legal reproducibility by context.

Real-world applications Sales proposals, contract pre-sign packets, renewal offers.

Where you’ll apply it This project and P07-crm-sync-integration.md.

References

  • Salesforce quote automation resources.
  • RFC 9110 for API semantics.

Key insights Deterministic rendering turns customer-facing artifacts into auditable outputs.

Summary Quote document quality depends on revision discipline and template governance.

Homework/Exercises to practice the concept Create two revisions with one changed discount and prove separate hashes.

Solutions to the homework/exercises Keep immutable revision ids and include render metadata in output.

3. Project Specification

3.1 What You Will Build

A quote rendering service with revisioning, clause resolution, and artifact metadata persistence.

3.2 Functional Requirements

  1. Create and lock quote revisions.
  2. Select template by segment/region.
  3. Apply clause packs conditionally.
  4. Render artifact and persist metadata.

3.3 Non-Functional Requirements

  • Performance: render under 2 seconds for standard quote.
  • Reliability: deterministic artifacts for same inputs.
  • Usability: clear status transitions.

3.4 Example Usage / Output

$ cpq quote render --quote Q-2026-0102 --revision R3
Rendered Q-2026-0102-R3.pdf (hash=93f1...)

3.5 Data Formats / Schemas / Protocols

  • QuoteRevision(id, quoteId, status, createdAt)
  • RenderMetadata(revisionId, templateVersion, clauseVersion, hash)

3.6 Edge Cases

  • Missing required clause for region.
  • Attempt to render unapproved revision.
  • Template version mismatch.

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

$ cpq quote create --fixture fixtures/quote_ready.json
$ cpq quote approve --quote Q-2026-0102 --revision R3
$ cpq quote render --quote Q-2026-0102 --revision R3

3.7.2 Golden Path Demo (Deterministic)

Same revision and template version should output same metadata hash.

3.7.4 If Web App

  • URL: /quotes/Q-2026-0102/revisions/R3
  • Buttons: Render PDF, Preview, Send
  • States: draft, approved, rendered, sent

ASCII wireframe:

+------------------------------------------------+
| Quote Revision R3                              |
| Status: Approved                               |
| Template: enterprise_standard_v7               |
| Clause Pack: us_saas_standard_v4               |
|------------------------------------------------|
| [Preview] [Render PDF] [Send]                  |
+------------------------------------------------+

4. Solution Architecture

4.1 High-Level Design

Quote Service -> Template Resolver -> Renderer -> Artifact Store

4.2 Key Components

| Component | Responsibility | Key Decisions | |———–|—————-|—————| | Revision Manager | Lifecycle control | immutable revisions | | Template Resolver | Template + clause selection | context routing matrix | | Render Worker | Artifact generation | deterministic pipeline |

4.4 Data Structures (No Full Code)

RenderRequest { quoteRevisionId, templateVersion, clausePackVersion }
RenderResult { artifactUri, hash, generatedAt }

4.4 Algorithm Overview

  1. Validate revision eligibility.
  2. Resolve template + clauses.
  3. Render artifact.
  4. Persist metadata.

5. Implementation Guide

5.1 Development Environment Setup

$ cpq seed --scenario quote-rendering
$ cpq test --suite quote-render

5.2 Project Structure

quote-service/
  src/
    revisions/
    templates/
    rendering/

5.3 The Core Question You’re Answering

“Can customer-facing quote documents remain beautiful, accurate, and auditable at the same time?”

5.4 Concepts You Must Understand First

  • Revision semantics
  • Clause matrix design
  • Deterministic rendering

5.5 Questions to Guide Your Design

  • Which states should lock edits?
  • What metadata proves document integrity?

5.6 Thinking Exercise

Design a dispute response packet for “wrong terms in quote”.

5.7 The Interview Questions They’ll Ask

  1. How do you ensure quote document reproducibility?
  2. How do you route legal clauses by region?
  3. How do you prevent unauthorized post-approval edits?

5.8 Hints in Layers

  • Hint 1: freeze data before render.
  • Hint 2: use versioned templates.
  • Hint 3: hash rendered output.

5.9 Books That Will Help

| Topic | Book | Chapter | |——-|——|———| | Separation of concerns | “Refactoring” | Ch. 6-10 | | System boundaries | “Clean Architecture” | Ch. 21 |

5.10 Implementation Phases

  • Phase 1: revision lifecycle.
  • Phase 2: template and clause routing.
  • Phase 3: render metadata and status integration.

5.11 Key Implementation Decisions

| Decision | Options | Recommendation | Rationale | |———-|———|—————-|———–| | Source of truth | PDF, canonical model | canonical model | auditability | | Clause logic | template code, routing matrix | routing matrix | maintainability |

6. Testing Strategy

6.1 Test Categories

| Category | Purpose | Examples | |———-|———|———-| | Unit | template selection | region matrix | | Integration | render pipeline | approved revision | | Regression | hash stability | fixed fixtures |

6.2 Critical Test Cases

  1. Render approved revision.
  2. Reject render on draft revision.
  3. Correct clause selection by region.

6.3 Test Data

Fixed quote fixtures with known hash snapshots.

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

| Pitfall | Symptom | Solution | |———|———|———-| | Template-side calculations | total mismatch | use canonical totals | | Missing clause routing keys | legal mismatch | explicit region matrix |

7.2 Debugging Strategies

  • Compare rendered totals to canonical totals.
  • Log selected clause pack ids.

7.3 Performance Traps

Avoid synchronous heavy rendering on request thread; offload to worker.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add branded themes.
  • Add quote preview mode.

8.2 Intermediate Extensions

  • Multi-language clause packs.
  • e-signature package export.

8.3 Advanced Extensions

  • Render diff viewer by revision.
  • Policy-driven clause experiments.

9. Real-World Connections

9.1 Industry Applications

  • Sales proposal automation.
  • Quote-to-contract handoff.

9.3 Interview Relevance

Shows operationally safe document pipelines for enterprise systems.

10. Resources

10.1 Essential Reading

  • Salesforce quote automation documentation.
  • RFC 9110 semantics.

10.2 Video Resources

  • Document workflow architecture talks.

10.3 Tools & Documentation

  • Template engine docs, PDF rendering docs.

11. Self-Assessment Checklist

  • I can reproduce a sent quote artifact from revision metadata.
  • I can prove which clauses were included and why.
  • I can prevent post-approval edits without revisioning.

12. Submission / Completion Criteria

Minimum Viable Completion:

  • Revision model and rendering work.
  • Metadata includes hash and template versions.

Full Completion:

  • Clause matrix validated by tests.
  • Lifecycle transitions enforced.

Excellence (Going Above & Beyond):

  • Add revision diff and legal audit timeline view.