This document summarises the modular orders API after the refactor. Treat it as the canonical map for where handlers live and which helpers keep behaviour consistent.

+- API/src/routes/orders/index.ts — registers the scoped order plugins. +- API/src/routes/orders/list.ts — team-scoped listing with pagination/filtering. +- API/src/routes/orders/create.ts — order creation (number generation, shipping resolution, inventory commits). +- API/src/routes/orders/detail.ts — detailed fetch with payments/items/deposits. +- API/src/routes/orders/invoice.ts — invoice generation + document storage. +- API/src/routes/orders/delivery-note.ts — delivery note PDF generation. +- API/src/routes/orders/payments.ts — payments ledger, deposit adjustments. +- API/src/routes/orders/items/ — item create/update/delete handlers. +- API/src/routes/orders/update.ts — partial updates, shipping overrides, manual inventory commits. +- API/src/routes/orders/dispatch.ts — dispatch status transitions.

Shared utilities now live under API/src/modules/orders/: +- constants.ts — enums, filters, defaults. +- schemas.ts — Zod validation for queries/payloads. +- mappers.ts — mapping helpers for orders/items. +- payments.ts — payment ledger + deposit utilities. +- pricing.ts — line amount maths. +- shipping.ts — shipping rule evaluation. +- inventory.ts — manual inventory adjustments + storefront synchronisation. +- order-number.ts — order number generation. +- totals.ts — subtotal/tax/shipping recalculation. +- addresses.ts / utils.ts — shared formatting helpers.

+- Authentication + membership checks are centralised via modules/orders/access (thin wrappers around shared guards). +- Every mutation invalidates cached documents and recomputes totals before returning mapped payloads. +- Manual-inventory orders emit order_commit events with quantity snapshots so storefront stock stays aligned. +- Shipping resolution evaluates rules using the extracted metrics helper, ensuring custom selections behave as before. + Update this file whenever new order plugins or helpers are introduced so future contributors can navigate the layout quickly.