BOM module (bom)

The bom module in src/cluster_erp/modules/bom/ holds the bill of materials (BOM) of each manufactured product breakdown. A BOM card names the product, model, and version it builds; it has numbered versions that move from draft to active to superseded, and each version has a tree of items. The module explodes a version into effective quantities for costing, production, and planning, and it serves the BOM tree that the routing scaffold of the production module reads to derive the operation BOM (eBOM).

At a glance¶

What the module does¶

• Keeps one BOM card per product breakdown with a base quantity, a usage type, and a status (src/cluster_erp/modules/bom/boms/models.py:17-79).
• Versions the structure: only drafts are editable, and at most one version per BOM is active (src/cluster_erp/modules/bom/bom_versions/models.py:19-42).
• Stores items as a tree inside a version, with find number, quantity, unit, scrap factor, cut sizes, make-or-buy choice, stock material, effectivity dates, and per-unit labour and cost figures (src/cluster_erp/modules/bom/bom_items/models.py:18-142).
• Copies reusable templates into a draft version (src/cluster_erp/modules/bom/bom_versions/services.py:544-651).
• Explodes a version into effective quantities and a rollup per breakdown (src/cluster_erp/modules/bom/bom_versions/services.py:722-820).
• Serves the explorer tree, where-used data, and a purchasing coverage snapshot (src/cluster_erp/modules/bom/bom_versions/services.py:822-836, src/cluster_erp/modules/bom/bom_versions/services.py:1141-1151, src/cluster_erp/modules/bom/bom_versions/services.py:1519-1520).
• Creates a BOM card with a first draft version when a design with a part is approved (src/cluster_erp/modules/bom/module.py:667-775).

Sub-modules¶

Data model¶

Quantities and money are Numeric: item quantity Numeric(18, 4), costs Numeric(18, 4), scrap factor Numeric(6, 4) (src/cluster_erp/modules/bom/bom_items/models.py:62-128). The product ids are plain UUID columns; the bom module checks them through the EventBus, not through database foreign keys (src/cluster_erp/modules/bom/boms/services.py:203-213).

Screens and metadata¶

get_metadata declares a sidebar group BOM Management (Turkish Ürün Ağacı Yönetimi) with four sections: BOM Explorer (the custom widget bom_explorer), Bills of Materials, BOM Versions, and BOM Templates (src/cluster_erp/modules/bom/module.py:838-905). The explorer tabs are labelled Product Tree · BOM (webapp/i18n/en.json key bom_explorer.tab.cs03) and Operation BOM · eBOM (webapp/i18n/en.json key bom_explorer.tab.ca03). The product card shows a read-only Bill of Materials tab for manufacturable products (src/cluster_erp/modules/products_and_services/products/metadata.py:276-285). Gated bundles are described on gated app bundles; the desktop explorer on desktop module screens.

Status and actions¶

A BOM card is active or archived; its usage type is manufacturing, engineering, or costing (src/cluster_erp/modules/bom/boms/schemas.py:10-11). A version moves from draft to active to superseded (src/cluster_erp/modules/bom/bom_versions/models.py:20-24).

The diagram shows a version's lifecycle.

stateDiagram-v2
 [*] --> draft: create, clone, or auto-BOM
 draft --> active: activate
 active --> superseded: supersede with a draft successor
 draft --> [*]: delete
 superseded --> [*]

In prose: a version is created as draft (src/cluster_erp/modules/bom/bom_versions/services.py:231-274). activate needs a draft with at least one live item and no other active version on the BOM (src/cluster_erp/modules/bom/bom_versions/services.py:417-474). supersede turns the active version into superseded and a draft of the same BOM into active in one call (src/cluster_erp/modules/bom/bom_versions/services.py:476-542). Only a draft can be deleted, and its items go with it (src/cluster_erp/modules/bom/bom_versions/services.py:305-333).

Business rules¶

• Creating or changing a BOM card checks that the product exists and that model and version belong to it (src/cluster_erp/modules/bom/boms/services.py:80-108, src/cluster_erp/modules/bom/boms/services.py:130-139).
• An archived BOM can only be set back to active (src/cluster_erp/modules/bom/boms/services.py:120-124).
• A BOM with an active or superseded version cannot be deleted; deleting a BOM soft-deletes its versions and their items (src/cluster_erp/modules/bom/boms/services.py:159-176, src/cluster_erp/modules/bom/boms/services.py:215-267).
• Items can be added or changed only in a draft version (src/cluster_erp/modules/bom/bom_items/services.py:135-137).
• A zero quantity is refused; a negative quantity is a co-product (src/cluster_erp/modules/bom/bom_items/services.py:139-146).
• Each item's breakdown is validated; a stock material without model and version takes the product's default ones (src/cluster_erp/modules/bom/bom_items/services.py:91-128, src/cluster_erp/modules/bom/bom_items/services.py:158-169).
• The item level comes from the parent chain; the chain may not loop or go deeper than MAX_BOM_DEPTH, which is 10 (src/cluster_erp/modules/bom/bom_items/services.py:32, src/cluster_erp/modules/bom/bom_items/services.py:430-470).
• A missing scrap factor becomes DEFAULT_SCRAP_FACTOR, 0.0300 (src/cluster_erp/modules/bom/bom_items/services.py:33, src/cluster_erp/modules/bom/bom_items/services.py:180-181).
• clone copies any version into a new draft with the next version number and all items (src/cluster_erp/modules/bom/bom_versions/services.py:335-415).
• Version totals: labour minutes and labour cost are per-unit figures times quantity; material cost is per-unit cost times quantity divided by one minus the scrap factor; weight sums the net weight of leaf items from the product master (src/cluster_erp/modules/bom/bom_versions/services.py:671-718).
• bom_code comes from the yearly sequence bom, and template_code from bom_template (src/cluster_erp/modules/bom/boms/services.py:89, src/cluster_erp/modules/bom/bom_templates/services.py:101).

Explosion and the operation BOM¶

The diagram shows how a BOM version becomes the explosion that other modules read, and how the routing scaffold reads the tree.

flowchart TD
 V["BomVersion and BomItem rows"] --> F["_filter_effective(as_of)"]
 F --> Q["effective_qty = qty / (1 - scrap), times each parent qty / (1 - parent scrap)"]
 Q --> A["operation_type and work_center_id from production allocations"]
 A --> R["rollup per part, model, version"]
 R --> X["GetBomExplosion answer"]
 X --> C["costing"]
 X --> P["production and MRP"]
 V --> S["GetBomScaffoldTree answer"]
 S --> W["production routing scaffold"]
 W --> I["CreateScaffoldIntermediate to products_and_services"]

In prose: explosion loads the live items of a version and drops items whose effectivity window does not contain the given date, with their whole subtree (src/cluster_erp/modules/bom/bom_versions/services.py:136-159, src/cluster_erp/modules/bom/bom_versions/services.py:734-741). For each item the effective quantity is the quantity divided by one minus its scrap factor, then multiplied by each parent's quantity divided by one minus that parent's scrap factor, rounded to four places with ROUND_HALF_EVEN; a negative co-product quantity takes no scrap (src/cluster_erp/modules/bom/bom_versions/services.py:128-133, src/cluster_erp/modules/bom/bom_versions/services.py:748-767). The operation type and work centre come from the production module's component allocations (src/cluster_erp/modules/bom/bom_versions/services.py:790-796). The rollup sums effective quantities per part, model, and version (src/cluster_erp/modules/bom/bom_versions/services.py:798-820). Other modules ask for it with GetBomExplosion (src/cluster_erp/modules/bom/module.py:217-228). The explosion follows parent links inside one version; the explorer tree additionally expands items that have their own active BOM (src/cluster_erp/modules/bom/bom_versions/services.py:1141-1151).

For the operation BOM, the production module's routing scaffold asks GetBomScaffoldTree with a full product breakdown. The bom module answers with the active version of exactly that breakdown, or a named version, and all its live items with resolved make-or-buy; it does not fall back to a default breakdown (src/cluster_erp/modules/bom/module.py:363-420, src/cluster_erp/modules/production/routings/scaffold.py:185-192). The scaffold turns non-phantom items into inputs of a final joining operation and lifts the children of phantom items; this is described in its module docstring (src/cluster_erp/modules/production/routings/scaffold.py:1-43). When an operation of a routing has an output, the scaffold asks products_and_services to create or reuse an intermediate product with CreateScaffoldIntermediate (src/cluster_erp/modules/production/routings/scaffold.py:2221-2239). The routing side is documented on routings and operation types.

Events and queries¶

The module consumes 15 contracts and produces 14, counted as on the parties module page. The full list is on the contracts reference.

Rules carried by the subscriptions:

• On DesignApproved, the module reads the design's part, takes that product's default model and version, and creates an active BOM card named after the design with a draft version 1. It skips a design without a part, a design that already owns a BOM, and a product without a default breakdown (src/cluster_erp/modules/bom/module.py:667-775).
• On ProductDeleted, the module soft-deletes the deleted product's items in draft versions only; active and superseded versions keep their rows (src/cluster_erp/modules/bom/module.py:777-816).

Permissions¶

Privacy, retention, and history¶

The module stores no personal data and has no privacy_handlers.py. Deletion is soft throughout, and version and item deletions cascade with the same actor (src/cluster_erp/modules/bom/boms/services.py:215-249). Changes are captured by change history.

Analytics facts¶

This module has no analytics_facts.py.

Settings and reference data¶

The module has no settings section. The stock-unit arithmetic for make-from-stock items reads the kerf, sheet gap, and edge-margin settings through core/stock_conversion.py (src/cluster_erp/modules/bom/bom_versions/services.py:95-125); see product breakdown and stock conversion.

Tests¶

Found by a grep for modules.bom in tests/ and by file name in web-client/.

Discrepancies¶

Terms introduced¶

Related pages¶

• Modules index
• Products and services module
• Design engineering module
• Costing module
• Production module
• Product breakdown and stock conversion
• API reference for this module

Verified against commit 92f8051 on 2026-11-13.