%% docs/cpq-subsystem.mmd
%%
%% Novel Systems — inside the CPQ engine, as merged.
%%
%% WHY THERE IS A SECOND DIAGRAM.
%%
%% docs/architecture.mmd draws the whole platform and gives CPQ four boxes:
%% the sandbox, the browser engine, the proxy route, the server engine. That is
%% the right resolution for "how does a request get from a browser to Postgres"
%% and the wrong resolution for the question a reviewer actually asked, which
%% was how the pricing subsystem is laid out internally. A review in August 2026
%% listed "CPQ subsystem layout" as a missing artifact while standing on a page
%% that served the request-flow render. It was not wrong. Zooming in on a
%% diagram drawn for a different scale does not answer a different question.
%%
%% So this file is the zoom. It draws one call to calculateQuote() and nothing
%% else: what is read, in what order the arithmetic happens, where each rounding
%% mode applies, and which of the two engines each box belongs to.
%%
%% WHAT IT IS A DRAWING OF.
%%
%% backend/src/services/cpq-engine.ts and lib/cpq-engine.ts, both at the commit
%% this was rendered from. Every constant on a node is declared in one of those
%% two files and checked by one of the three parity scripts drawn at the bottom.
%% Nothing here is aspirational and nothing here is a status — see the header of
%% architecture.mmd and scripts/check-diagram-current.mjs for why that rule
%% exists and what it cost to learn.
%%
%% THE STRUCTURAL CLAIM WORTH DRAWING.
%%
%% Two engines compute the same prices and cannot import from each other. One is
%% bundled into the browser so the marketing calculator can respond without a
%% network round trip; the other must never reach a browser, because it reads
%% rate cards and a rate card is the customer's commercial position. The
%% duplication is forced. What holds them together is the row of checks along the
%% bottom — a fixture neither engine imports, held against both. See D-002 and
%% D-010.
%%
%% Render:  double-click render-diagram.command in the repository root. It renders
%%          every docs/*.mmd through the Chrome already installed on the machine.
%%          mermaid-cli is not used; it needs a Chromium that does not exist for
%%          arm64 Linux, which is what this repository is built on.

flowchart TB

  %% ── Callers ────────────────────────────────────────────────────────────
  subgraph callers["Two callers, two engines, one arithmetic"]
    direction LR
    sandbox["CPQ sandbox<br/><i>components/cpq — marketing page</i><br/><b>no network, no rate card</b>"]
    apicall["POST /api/v1/quotes/calculate<br/><i>Bearer JWT · ADMIN · SALES</i>"]
  end

  browserEngine["lib/cpq-engine.ts<br/><b>bundled to the browser</b><br/><i>list prices only, published in the module</i>"]
  serverEngine["services/cpq-engine.ts — calculateQuote()<br/><b>never bundled to a browser</b>"]

  %% ── What the server reads before it can price anything ─────────────────
  subgraph inputs["Resolved before pricing, inside withTenant()"]
    direction LR
    skus[("inventory_skus<br/><i>costPerUnitCents · yieldFactor · type</i>")]
    tiers[("labor_tiers<br/><i>hourlyRateCents · multiplier</i>")]
  end

  %% ── The gate ───────────────────────────────────────────────────────────
  %% Drawn before the arithmetic because that is where it runs. A margin that
  %% cannot be honoured is refused before a single line item is costed.
  gate{{"Margin gate — before any price exists<br/>appliedMargin &gt; 0.95 → 400<br/>appliedMargin &lt; 0.50 without an approved override → <b>400, not a clamp</b><br/><i>a quote that silently differs from the request is worse than an error</i>"}}

  %% ── Per line item ──────────────────────────────────────────────────────
  subgraph line["calculateLineItem() — once per line"]
    direction TB

    validate["assertDimensions · assertSkuType<br/><i>6&quot; floor · 144&quot; width · 180&quot; drop · 500 per line</i><br/><i>fabric is FABRIC, motor is MOTOR — types are checked, not assumed</i>"]
    area["openingSquareFeet = W × D ÷ 144<br/><i>the divisor is written out, not pre-computed</i>"]

    subgraph components["Component costs — each rounded half-up to the cent"]
      direction TB
      fabric["fabric · sq ft<br/>opening × yieldFactor × <b>1.15</b> × qty<br/><i>waste applied on top of yield, not folded into it,<br/>so a contractor can argue with either</i>"]
      hardware["hardware · each<br/>yieldFactor × qty"]
      motor["motor · each <i>(optional)</i><br/>yieldFactor × qty"]
      trim["trim · linear in <i>(optional)</i><br/>width × yieldFactor × qty"]
      labour["labour · hours<br/>0.75/unit + 0.05/sq ft + <b>0.5 if motorised</b><br/>rate = hourlyRateCents × tier multiplier<br/><i>the multiplier scales the rate, never the hours —<br/>a costly market pays more, it does not take longer</i>"]
    end

    cost["costCents = Σ already-rounded components"]
    price["priceCents = <b>roundCentsUp</b>( cost ÷ (1 − margin) )<br/><i>costs are measurements and round to the nearest;<br/>this is a constraint and rounds away from the violation</i>"]
  end

  %% ── Cut list, deliberately off to the side ─────────────────────────────
  cutlist["calculateCutList( W, D )<br/>tube = W − 1.25 · hembar = W − 1.00<br/>fabric = (W − 1.50) × (D + 4.00 wrap)<br/><i>derived from the finished opening, never from a costed intermediate</i>"]
  cutnote["A work order needs cut sizes and has no business<br/>asking for a price to get them. Coupling a shop-floor fact<br/>to a commercial one is how the two come apart."]

  %% ── Totals and the assertion ───────────────────────────────────────────
  totals["totals = Σ line items<br/><i>the sum of rounded lines, not a re-rounding of the unrounded sum —<br/>the lines on the printed proposal have to add up to the total under them</i>"]
  assertion{{"realisedMargin(total) &lt; 0.50 → 400<br/><b>should be unreachable</b><br/><i>which is why it is here: it catches a future change to<br/>the rounding direction, the line pricing or the totalling</i>"}}

  result["QuoteCalculation<br/><i>lineItems · components · cutList · totals · assumptions</i><br/><b>marginFloor and appliedMargin are both in the response</b>"]

  %% ── Downstream ─────────────────────────────────────────────────────────
  persist["POST /api/v1/quotes → withTenant()<br/><i>one transaction, one declared tenant</i>"]
  approved(["quote.approved<br/><i>after commit</i>"])
  downstream["webhook dispatcher · integration fan-out<br/><i>drawn in full at /architecture.png</i>"]

  %% ── Flows ──────────────────────────────────────────────────────────────
  sandbox --> browserEngine
  apicall --> serverEngine
  skus --> serverEngine
  tiers --> serverEngine

  serverEngine --> gate
  gate -->|"margin accepted"| validate
  validate --> area
  area --> fabric
  area --> labour
  validate --> hardware
  validate --> motor
  validate --> trim

  fabric --> cost
  hardware --> cost
  motor --> cost
  trim --> cost
  labour --> cost
  cost ==> price

  validate ==>|"from W and D alone"| cutlist
  cutlist -.- cutnote

  price --> totals
  cutlist --> result
  totals --> assertion
  assertion -->|"holds"| result
  result --> persist
  persist --> approved
  approved --> downstream

  %% ── What holds the two engines together ────────────────────────────────
  subgraph parity["The two engines cannot import each other, so this is what pins them"]
    direction LR
    fixture[("fixtures/cut-list-parity.json<br/><b>read by both checks, imported by neither engine</b><br/><i>pins the values, not the constants</i>")]
    cutcheck["check:cutlist-parity<br/><i>both files declare the same four allowances</i>"]
    valuecheck["check:cpq-parity + backend/test/cpq-engine.test.ts<br/><i>each engine reproduces the fixture's numbers</i>"]
    margincheck["check:margin-policy<br/><i>both files declare MARGIN_FLOOR 0.50</i>"]
  end

  paritynote["Identical constants still produce different cut sizes if one engine<br/>transforms its input before subtracting from it. That is not hypothetical:<br/>the browser engine snapped to the quarter inch and cut a 30.1&quot; opening<br/>to 29.00&quot; where the API cut 28.85&quot; — from constants that agreed.<br/>So the fixture pins the answers."]

  browserEngine -.- cutcheck
  serverEngine -.- cutcheck
  browserEngine -.- valuecheck
  serverEngine -.- valuecheck
  browserEngine -.- margincheck
  serverEngine -.- margincheck
  cutcheck -.- fixture
  valuecheck -.- fixture
  fixture -.- paritynote

  %% ── Styling ────────────────────────────────────────────────────────────
  classDef engine fill:#eef2ff,stroke:#4338ca,color:#312e81
  classDef boundary fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d
  classDef store fill:#f0fdf4,stroke:#15803d,color:#14532d
  classDef annotation fill:#f8fafc,stroke:#94a3b8,stroke-dasharray:3 3,color:#475569
  classDef arith fill:#fffbeb,stroke:#b45309,color:#78350f

  class browserEngine,serverEngine engine
  class gate,assertion,price,persist boundary
  class skus,tiers,fixture store
  class cutnote,paritynote annotation
  class fabric,hardware,motor,trim,labour,area,cost,totals,cutlist arith