PolyWood Price Builder

Architecture

Purpose

pw_price_builder is a Next.js app for building price rules, versioning them, assigning them to products, and previewing final prices.

Stack

  • Next.js App Router (src/app)
  • React 19 + TypeScript
  • Tailwind CSS v4
  • AWS SDK v3 for S3-backed storage
  • Lucide React for iconography
  • ReactFlow packages remain in package.json, but the active builder UI is currently a draggable ordered pipeline list in src/app/ruleset-builder/page.tsx.

High-Level Module Map

  • src/app/page.tsx: products table, CSV upload/download, product-to-ruleset assignment controls, and computed T1-T5 output columns.
  • src/app/rules/page.tsx: ruleset catalog/list view with load/edit/delete actions.
  • src/app/ruleset-builder/page.tsx: ruleset authoring workflow (ruleset ID editing, widget pipeline steps, tier policy editor, pipeline/tier preview, save/publish behavior).
  • src/app/widgets/page.tsx: read-only widget catalog viewer.
  • src/app/settings/page.tsx: placeholder settings screen.
  • src/app/api/*: server-side JSON/CSV endpoints.
  • src/lib/rules.ts: pricing execution engine.
  • src/lib/tier-pricing-policy.ts: tier policy types, parsing, defaults, and T1-T5 computation.
  • src/lib/widgets.ts: widget/step schema and defaults.
  • src/lib/s3-products.ts: product CSV storage adapter.
  • src/lib/s3-rulesets.ts: ruleset + assignment storage adapter.
  • src/lib/s3-widgets.ts: widget catalog storage adapter.
  • src/lib/dev-aws-env.ts: shared DEV AWS credential and region readers for all S3 clients.
  • src/lib/products-csv.ts: CSV parser/serializer and validation.

Core Runtime Flows

  • Products flow:
    • UI calls /api/products.
    • API loads CSV from S3 and parses it.
    • If object is missing, app falls back to DEFAULT_PRODUCTS.
  • Ruleset authoring flow:
    • Builder page loads /api/widgets and /api/rule-assignments on init.
    • If ?id=<rulesetId> is present, it also loads /api/rulesets?id=<rulesetId>&version=latest.
    • Saving posts { id, steps, tierPolicy } to /api/rulesets; backend auto-creates v0001 or publishes the next version.
  • Assignment and preview flow:
    • Products page loads /api/rulesets, /api/rule-assignments, and /api/widgets in parallel.
    • Per assigned product, it computes pipeline output (applyPipeline) and tier values (computeTierPrices) for T1-T5 columns.
  • Persistence flow:
    • Products CSV is stored in S3.
    • Rulesets, versions, latest snapshot, assignments, and widgets are stored as JSON in S3.

Important Design Reality

  • src/app/rules/page.tsx is no longer the rules builder; it is a ruleset list page.
  • Rules are widget-driven (RuleStep is { id, widgetId, config }) with strict API validation against the live widget catalog.
  • Ruleset versions persist tierPolicy with each version payload.
  • Storage read paths use lenient normalization for backward compatibility of stored data, but API write paths are strict.