00 — Manufacturing Module: Architecture & Design Principles

READ THIS FIRST. This document governs how the entire Manufacturing module must be designed. Every other spec file inherits these principles. The module must be generic (works for any manufacturer). The Melamine tableware factory is used only as a stress-test example to prove genericity.

0.1 Purpose & Scope

Build a generic Manufacturing module that plugs into an existing ERP (which already has Finance/GL, Inventory, Procurement, Sales, HR).

The module covers the full production lifecycle:

Master Data → Planning → Execution → Costing

Plus a Shop Floor Control (SFC) layer for real-time operation tracking, and integration points to the existing ERP modules.

Out of scope (already exist in the host ERP, integrate — do not rebuild): General Ledger, Inventory/Warehouse core, Procurement core, Sales orders, HR/payroll.

0.2 The Genericity Mandate (CRITICAL)

The single most important rule: never hard-code one factory's behaviour. Every factory-specific behaviour must be expressed as configuration (a field/enum) + branching logic, not as a separate code path.

The design was validated against a Melamine factory whose complexity exposed the fields the system must support. Examples of how factory-specific behaviour becomes generic configuration:

Rule of thumb for the AI builder: when you encounter a behaviour that "only this factory does," do NOT branch the code by factory. Add a configuration field that defaults to the common behaviour, and branch on that field.

0.3 The Four-Layer Architecture

┌──────────────────────────────────────────────────┐
│  SHOP FLOOR CONTROL (SFC) — real-time tracking     │  ← cross-cuts Execution
├──────────────────────────────────────────────────┤
│  ① MASTER DATA   — the foundation (definitions)    │
│  ② PLANNING      — the brain (what/how much/when)  │
│  ③ EXECUTION     — reality (actual events)         │
│  ④ COSTING       — money (translate to figures)    │
└──────────────────────────────────────────────────┘
        ↕ integrates with: Inventory, Procurement, Sales, GL, HR

Data flows top-down (Master Data feeds Planning feeds Execution feeds Costing), with a closed loop: Costing variances and CRP capacity conflicts feed back to correct Planning.

0.4 Cross-Cutting Design Rules

These apply to EVERY entity and process in the module:

1. Frozen Snapshots. When a Production Order is released, it must snapshot the active BOM and Routing. Later changes to master data must NOT affect already-released orders. This protects historical cost and audit trail.

2. Status as State Machine. Every transactional entity (Order, Issue, Confirmation, GR) has an explicit status with defined transitions, preconditions, and side-effects. No ad-hoc status changes.

3. Many-to-Many Demand↔Supply. A sales order can split into many production orders (delivery batches); a production order can serve many sales orders (batching to reduce setup). A Pegging table records the links.

4. Multi-level everything. BOM, orders, and costing must support arbitrary nesting (finished good → sub-assembly → component → raw material). Use recursion.

5. Configuration over code. See §0.2. Every variant point is a field.

6. Every actual event posts an accounting entry. Material issue, confirmation, and goods receipt each generate GL postings. Costing is not a separate batch step bolted on later — it is woven into execution.

7. Resource abstraction. Capacity is consumed by Resource objects of different resource_type (Machine, Tool, Labor). The effective capacity of an operation is constrained by the minimum available across all required resources.

0.5 Key Enumerations (used across the module)

production_type     ∈ { MakeToStock, MakeToOrder, AssembleToOrder, TollManufacturing }
material_ownership  ∈ { Own, Customer }
procurement_type    ∈ { Buy, Make }
costing_method      ∈ { Standard, Actual, Average, FIFO }
labor_calc          ∈ { Hourly, PieceRate }
issue_type          ∈ { Manual, Backflush, AutoIssue }
issue_level         ∈ { PerOrder, PerShift, PerOperation }
resource_type       ∈ { Machine, Tool, Labor }
lot_sizing_rule     ∈ { Exact, Fixed, MinMax, EOQ, PeriodOrder }
order_status        ∈ { Planned, Released, InProcess, Completed, Closed }
operation_status    ∈ { Waiting, Ready, InProgress, Completed }

0.6 How to Use These Specs (for the AI builder)

1. Read this file (00) fully — it sets the rules.
2. Build in dependency order: Master Data → Planning → Execution → Costing → SFC.
3. Each spec file has: Purpose, Entities & Fields, Logic/Algorithms (pseudo-code), Generic-design notes, Melamine test case.
4. The pseudo-code is language-agnostic intent, not literal code. Implement idiomatically in the host ERP's stack.
5. Honour the genericity mandate: the Melamine test cases prove the design handles edge cases — they are NOT the spec to hard-code.
6. The full relational data model is consolidated in file 06.

0.7 Build Status Reference (from the analysis)