Overview

This section documents the platform's stock & supplier-ordering system: a signed stock ledger that tells the physical truth, an event-driven reordering engine that regenerates supplier orders whenever demand changes, and a three-stage email pipeline (stage → review → send) guaranteeing that what the operator reviews is exactly what goes out. This page is the map: the actors, the end-to-end flow, the data model, and where to find the detail on each subsystem.

The actors

The system map

The nominal flow, from storefront order to the ledger write at reception:

flowchart TB
  PS["Customer order<br/>(PrestaShop storefront)"]
  PS -->|real-time webhook| WH["/api/webhooks/prestashop"]
  PS -->|"catch-up sync (3 h)"| SYNC["Order-sync cron"]
  WH --> ORD[("Local Order")]
  SYNC --> ORD
  BO["Merchant back office"] -->|create / edit / cancel| ORD
  ORD -->|event producers| Q{{"bext queue<br/>supplier-orders-recalc"}}
  Q -->|under write lock| RECALC["recalculateVendorOrdersUnified"]
  RECALC --> SO["Supplier order<br/>drafts (DRAFT)"]
  SO -->|"06:00 stage (render-only)"| MAIL["Email queue — operator review"]
  MAIL -->|approved send| VEND["Vendors (×159)"]
  VEND -->|delivery| RCPT["Confirmed reception"]
  RCPT -->|"StockAction COMPLETED (+)"| LEDGER[("Product.stockLedger")]
  BO -->|"customer-delivery seal (−)"| LEDGER

Read top to bottom:

1. Demand intake — a customer order arrives twice: in real time via webhook, and via the 3-hourly sync cron that catches anything the webhook missed (both paths converge on the same local Order, idempotently).
2. Event-driven reordering — every customer-order create/update/cancel/status change (plus: supplier-order cancellation, reception, product webhook) pushes a message onto the bext supplier-orders-recalc queue. The worker recalculates the affected vendor's drafts under the supplier write lock, which serializes it against the reordering cron. Detail: Supplier orders.
3. Three-stage email — the 06:00 cron renders each draft's email (render-only, nothing is sent), the operator reviews and adjusts in the review queue, then sending re-renders from the current items and blocks if quantities drifted since the stage. Review == sent.
4. Stock only moves on physical events — customer delivery decrements, supplier reception increments. Order sync never touches stock (that path was deleted on 2026-06-14). Detail: Write paths.

The two-column stock model

Since the backorder cutover (#2886 "Option B", STOCK_LEDGER_ALLOW_BACKORDER=true in production since 2026-07-09), stock lives in two columns with distinct roles:

flowchart LR
  MV["recordPhysicalMovement<br/>(every physical movement)"] --> SA["StockAction COMPLETED<br/>± quantity"]
  SA -->|same transaction| L[("Product.stockLedger<br/>SIGNED authority<br/>negative = backorder")]
  L -->|"stock = max(0, stockLedger)"| S[("Product.stock<br/>clamped display mirror")]
  L -->|"trustedStock (guardrails)"| R["Reordering engine"]
  S --> UI["Storefront / back-office display"]

• Product.stockLedger is the signed authority: opening + Σ receptions − Σ deliveries. It may go negative — that is a real backorder (delivered to the customer before the covering reception was recorded), and the next reception nets it out. Because it is never clamped, phantom stock (a counter inflated by a clamp at 0) is structurally impossible.
• Product.stock is the display mirror: the invariant is stock == max(0, stockLedger). It is what the storefront and back-office lists show; it drives no reordering decision.
• Every physical write goes through StockLedgerService.recordPhysicalMovement (pure math in packages/services/src/stock/rolling-stock-math.ts): it checks manageStock, emits the StockAction and updates both columns in the same transaction. No write site bypasses this contract — see Write paths.
• The reordering read side goes through trustedStock() (packages/services-supplier-order/src/utils/supplier-order-utils-new.ts), which applies the guardrails: manageStock=false → 0, the STOCK_LEDGER_PESSIMISTIC kill switch → 0 (OFF in production), negatives clamped to 0 (until the STOCK_TRUST_ALLOW_NEGATIVE gate is armed), and an anti-phantom ceiling of STOCK_TRUST_MAX_COVER_WEEKS weeks of recent consumption (8 in production). Detail: Ledger and Configuration.

The StockAction rows form the journal: statuses PENDING (projection — e.g. the "virtual inflow" expected from a sent supplier order) / COMPLETED (applied to the ledger) / CANCELLED; types INCREMENT / DECREMENT / ADJUSTMENT; sources MANUAL, ORDER_UPDATE, SUPPLIER_DELIVERY, INVENTORY_ADJUSTMENT, etc. Only COMPLETED actions count toward the ledger.

The daily rhythm at a glance

The full timeline, with cron interactions and alerting pitfalls, is on Daily timeline.

The subsystems

Three invariants to remember

1. The ledger tells the physical truth. Stock only moves on delivery or reception, never at order intake. A negative stockLedger is information (a backorder), not an error.
2. Never order into the past. The SUPPLIER_NO_PAST_SLOTS gate enforces a floor at now, causality (send ≥ creation of the source order), and rolls late demand forward to the next future slot.
3. What the operator reviews is what goes out. Sending a supplier email re-renders from the current items and refuses (CONFLICT) if the items fingerprint changed since the stage. A cancelled order is never emailed.

To check system health at any time, run the invariant audit from the application repo:

cd apps/app && bun run cli --task stock-ledger-audit \
  --tenantId <tenant> --siteId <site> --strict   # exits non-zero on any violation

Where to go next

• New to the system → read Ledger then Supplier orders: they are the two halves of the model.
• Writing code that touches stock → Write paths first, then Safety nets to know which tests to pin.
• Operating production → Daily timeline for the schedules, Configuration for the gates, and Back office for the control surfaces.
• Debugging a PrestaShop divergence → PrestaShop sync.

See also

• Stock ledger — the signed model in detail
• Supplier orders — event-driven reordering and the email pipeline
• Daily timeline — the 7 crons hour by hour
• Safety nets — invariants, audit, tests