New assembly item (spec → BOM → NS)

New assembly item (spec → BOM → NS)

New assembly item creation is the longest cascade on the platform. A new product introduces fifteen-plus downstream effects: catalog rows, BOM rollup, NS records, a PDF spec sheet, pricing pipeline registration, brand routing, bid eligibility, customer programs that should price it, and notifications to customers within the shared brand line.

Each step has a precondition or conditional. The workflow gate (Mike's approval) sits after spec parsing and BOM definition but before any write — once approved, the cascade is deterministic.

Risk level 4 (high). A bad spec going live could ripple into bids, quotes, and customer-facing pages. The 4-stage HITL gates (allergen validation, BOM completeness, spec sheet review, customer notification) exist precisely for that reason.

Trigger conditions

• A new product spec sheet is uploaded via /intake.html.
• An intake form is filled out by sales for a custom-formulated assembly.
• A brand line expansion (e.g. new Melt Mates SKU) is in the pipeline.
• A USDA commodity program adds a new item.
• A customer-specific co-pack lands and needs a SKU.

The 8 beats

1. 01

   Write spec_items + spec_versions

   INSERT into spec_items (the live spec) and spec_versions (the audit trail, with changed_field=created, new_value=full_json).

   Writes spec_items, spec_versions

   Time ~120ms

   Kind d1_write

   Status stub
2. 02

   Write items shell

   INSERT into items with the basic shell (itemid, isinactive=F). NS will populate the rest after push. Parallel with write_spec_items.

   Writes items

   Time ~80ms

   Kind d1_write

   Status stub
3. 03

   Recompute assembly cost rollup (conditional)

   If is_assembly, call recompute_assembly_cost_rollup to compute raw + packaging + labor + overhead + freight from the BOM components.

   Writes assembly_cost_rollup

   Time ~300ms

   Kind chat_tool

   Status stub

   Note conditional · is_assembly
4. 04

   NS item record

   Enqueue a NS push to create the item record via customscript_gfs_platform_query RESTlet. The NS record is the system of record; this push is load-bearing.

   Writes NetSuite item record

   Time ~3–8s

   Kind ns_push

   Status stub

   Note retry · 2 attempts linear backoff
5. 05

   NS BOM record (conditional)

   If is_assembly, enqueue a NS BOM push with the components and quantities.

   Writes NetSuite BOM record

   Time ~3–8s

   Kind ns_push

   Status stub

   Note conditional · is_assembly
6. 06

   Generate spec sheet PDF

   POST /api/spec/generate renders the spec sheet template via Browser Rendering and stores at specs/{item_code}.pdf in R2.

   Writes R2 bucket specs/

   Time ~6–10s

   Kind http_call

   Status stub
7. 07

   Pricing pipeline registration

   INSERT into pricing_master for every customer program that should price this new item. Source-tagged so downstream knows it came from new-item creation.

   Writes pricing_master

   Time ~200ms per N programs

   Kind d1_write

   Status stub
8. 08

   Customer notification (conditional)

   If shared_brand_customers is non-empty, draft a notification email per customer in the shared brand. Mike approves before send.

   Writes outbound_email_log

   Time ~80ms per customer

   Kind hitl_email_draft

   Status stub

   Note conditional · shared brand customers > 0

What's different after the workflow runs

• A new spec_items row + spec_versions audit row exist.
• A new items shell row exists with NS push enqueued.
• NS has the item record (and BOM if assembly).
• Spec sheet PDF is in R2.
• pricing_master has eligibility rows for matching customer programs.
• Shared-brand customers have a draft notification waiting.
• reflexion_log carries a new_spec,brand:?,category:? tagged row.
• Knowledge corpus is queued for reindex.

What can go wrong and how to recover

Adjacent workflows + diagrams

Code paths + invariants