Project 1: Product Catalog with Configurable Products

Build a versioned product catalog and compatibility model that makes invalid configurations impossible to quote.

Quick Reference

Attribute Value
Difficulty Level 2 (Intermediate)
Time Estimate 1-2 weeks
Main Programming Language Python (Alternatives: TypeScript, Java, Go)
Coolness Level Level 2
Business Potential 3. Service & Support Model
Prerequisites Relational modeling, API fundamentals, basic graph thinking
Key Topics Catalog versioning, dependencies, exclusions, validation diagnostics

1. Learning Objectives

By completing this project, you will:

  1. Design a catalog model that supports base SKUs, options, bundles, and relationships.
  2. Implement version-aware validation so historical quotes remain reproducible.
  3. Return structured diagnostics for invalid selections.
  4. Explain catalog tradeoffs clearly in architecture interviews.

2. All Theory Needed (Per-Concept Breakdown)

Concept A: Versioned Product Modeling

Fundamentals A CPQ catalog is a domain model, not a simple product table. You must represent option structure, compatibility, lifecycle dates, and version references so that each quote can be tied to immutable commercial truth.

Deep Dive into the concept Most production failures in CPQ start when teams mutate catalog records in place. Use immutable versions with effective dates and deprecation markers. Keep relationships typed (requires, excludes, recommends) and avoid opaque JSON blobs for core compatibility logic.

How this fit on projects Primary in this project. Reused heavily in P02-config-rules-engine.md, P06-guided-selling-assistant.md, and P08-product-rules-dsl.md.

Definitions & key terms

  • Catalog version: immutable product snapshot.
  • Option family: related selectable choices.
  • Compatibility edge: typed relation between options.

Mental model diagram

CatalogVersion
  -> Products
     -> OptionGroups
        -> Options
           -> Relations (requires/excludes/recommends)

How it works

  1. Resolve quote date to one catalog version.
  2. Load base product and candidate options.
  3. Validate relationship graph against current selection.
  4. Return deterministic decision packet.

Minimal concrete example

if selection includes SSO then require API_ACCESS
if selection includes STARTER_SUPPORT then forbid ENTERPRISE_TIER

Common misconceptions

  • “Versioning is optional.” It is required for audit replay.
  • “Names are enough.” Stable ids are required.

Check-your-understanding questions

  1. Why bind quotes to version ids?
  2. Why type relationship edges?

Check-your-understanding answers

  1. To preserve replayability when catalog changes.
  2. To make rule execution explicit and maintainable.

Real-world applications SaaS packaging, telecom plans, manufacturing option kits.

Where you’ll apply it This project and P02-config-rules-engine.md.

References

  • “Domain-Driven Design” by Eric Evans - Ch. 5-9
  • Salesforce pricing data model docs

Key insights Catalog quality is the foundation of CPQ trust.

Summary Use immutable versions, typed relationships, and deterministic diagnostics.

Homework/Exercises to practice the concept

  1. Model one product family with 12 options.
  2. Add two incompatible option pairs.

Solutions to the homework/exercises

  1. Split options by groups and explicit relations.
  2. Add excludes edges and verify validation output.

3. Project Specification

3.1 What You Will Build

A catalog service with APIs for product retrieval, version lookup, and configuration validation.

3.2 Functional Requirements

  1. Create and publish catalog versions.
  2. Validate selection against dependencies/exclusions.
  3. Return violations, suggestions, and auto-additions.
  4. Support effective-date resolution.

3.3 Non-Functional Requirements

  • Performance: p95 validation under 150ms for 200 rules.
  • Reliability: deterministic output for identical inputs.
  • Usability: errors understandable by sellers.

3.4 Example Usage / Output

POST /api/v1/configurations/validate
selection=[BASE_ENTERPRISE,SSO]
-> valid=false, violation=SSO requires API_ACCESS

3.5 Data Formats / Schemas / Protocols

  • CatalogVersion(id, effectiveStart, effectiveEnd, status)
  • Product(id, versionId, sku, type)
  • Relation(sourceOptionId, relationType, targetOptionId)

3.6 Edge Cases

  • Circular dependencies.
  • Overlapping effective-date ranges.
  • Option references missing in version.

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

$ cpq catalog publish --file fixtures/catalog_v2026_03.json
$ cpq config validate --catalog-version 2026.03 --selection BASE_ENTERPRISE,SSO

3.7.2 Golden Path Demo (Deterministic)

Input: BASE_ENTERPRISE, API_ACCESS, SSO Expected: valid=true, no violations.

3.7.3 If API: Request/Response

{
  "valid": false,
  "violations": [{"ruleId":"R_DEP_012","message":"SSO requires API_ACCESS"}],
  "autoAdditions": ["API_ACCESS"]
}

4. Solution Architecture

4.1 High-Level Design

API -> Catalog Resolver -> Rule Evaluator -> Decision Packet

4.2 Key Components

| Component | Responsibility | Key Decisions | |———–|—————-|—————| | Catalog Resolver | Selects correct version | Effective-date lookup | | Rule Evaluator | Validates constraints | Typed relation checks | | Diagnostics Builder | Human-readable output | Stable rule ids |

4.3 Data Structures (No Full Code)

SelectionContext { versionId, segment, region, selectedOptionIds }
RuleResult { ruleId, severity, message, correctiveAction }

4.4 Algorithm Overview

  1. Resolve version.
  2. Build candidate rule set from selected options.
  3. Evaluate and aggregate diagnostics.
  4. Return deterministic result.

Complexity:

  • Time: O(r) where r is matched rules.
  • Space: O(r + s).

5. Implementation Guide

5.1 Development Environment Setup

$ docker compose up -d
$ cpq migrate
$ cpq seed --scenario catalog-foundation

5.2 Project Structure

catalog-service/
  src/
    catalog/
    validation/
    api/
  tests/
  fixtures/

5.3 The Core Question You’re Answering

“Can the system prevent invalid commercial combinations before pricing starts?”

5.4 Concepts You Must Understand First

  1. Entity versioning
  2. Constraint graph checks
  3. Deterministic diagnostics

5.5 Questions to Guide Your Design

  1. Which fields are immutable after publish?
  2. How will you represent multi-option dependencies?

5.6 Thinking Exercise

Draw one invalid configuration and trace every violated rule.

5.7 The Interview Questions They’ll Ask

  1. How do you version catalogs safely?
  2. How do you avoid circular dependency issues?
  3. How do you keep validation explainable?

5.8 Hints in Layers

  • Hint 1: start with requires and excludes only.
  • Hint 2: add relation indexes for performance.
  • Hint 3: persist rule evidence ids.

5.9 Books That Will Help

| Topic | Book | Chapter | |——-|——|———| | Domain modeling | “Domain-Driven Design” | Ch. 5-9 | | API discipline | “The Pragmatic Programmer” | Ch. 4 |

5.10 Implementation Phases

  • Phase 1: Data model + migration.
  • Phase 2: Validation runtime.
  • Phase 3: Diagnostics and tests.

5.11 Key Implementation Decisions

| Decision | Options | Recommendation | Rationale | |———-|———|—————-|———–| | Catalog mutation | In-place, versioned | Versioned | Audit and replay safety | | Relation storage | Free text, typed enum | Typed enum | Deterministic runtime behavior |

6. Testing Strategy

6.1 Test Categories

| Category | Purpose | Examples | |———-|———|———-| | Unit | Rule checks | dependency/exclusion | | Integration | API + DB | version resolution | | Edge Case | invalid catalog | circular relation |

6.2 Critical Test Cases

  1. Missing required dependency.
  2. Mutual exclusion conflict.
  3. Historical quote replay against old version.

6.3 Test Data

Use fixed fixtures: catalog_v2026_03.json, selection_cases.json.

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

| Pitfall | Symptom | Solution | |——–|———|———-| | In-place updates | historical mismatch | immutable versions | | Missing relation index | latency spikes | build option->rule index |

7.2 Debugging Strategies

  • Re-run deterministic fixtures with hash comparison.
  • Log version id and rule ids for every validation call.

7.3 Performance Traps

Avoid full-rule scans on every selection change.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add recommendation-only rules.
  • Add severity levels.

8.2 Intermediate Extensions

  • Multi-region policy overlays.
  • Auto-additions with user confirmation.

8.3 Advanced Extensions

  • Partial evaluation caching.
  • Rule simulation dashboard.

9. Real-World Connections

9.1 Industry Applications

  • Enterprise SaaS packaging.
  • Industrial bundle compatibility checks.

9.3 Interview Relevance

Demonstrates modeling rigor, rule explainability, and deterministic API behavior.

10. Resources

10.1 Essential Reading

  • “Domain-Driven Design” by Eric Evans - modeling and ubiquitous language.
  • Salesforce pricing data model docs.

10.2 Video Resources

  • Revenue operations architecture talks from Salesforce events.

10.3 Tools & Documentation

  • PostgreSQL docs for relational modeling.
  • OpenAPI docs for API contracts.

11. Self-Assessment Checklist

  • I can explain why versioned catalogs are necessary.
  • I can trace invalid configuration decisions from rule ids.
  • I can replay historical validations deterministically.

12. Submission / Completion Criteria

Minimum Viable Completion:

  • Versioned catalog persisted.
  • Validation endpoint functional.
  • Rule diagnostics returned.

Full Completion:

  • Deterministic replay tests pass.
  • Performance target met.
  • Integration tests for edge cases pass.

Excellence (Going Above & Beyond):

  • Simulation harness for bulk scenarios.
  • Clear business-facing diagnostic wording.