# 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:

| Factory-specific reality (Melamine) | Generic mechanism in the system |
|---|---|
| Make-to-order, make-to-stock, toll manufacturing all happen | `production_type` enum + branching |
| Customer supplies raw material (toll) | `material_ownership` enum {Own, Customer} |
| One press cycle yields multiple pieces (multi-cavity mold) | `cavity_count` field on the tool/operation |
| One cycle produces grades A/B/C at different prices | Joint-products: yield is a **distribution**, not a scalar |
| Press operator paid per piece, others fixed salary | `labor_calc` enum {Hourly, PieceRate} |
| Worker draws powder for a whole shift | `issue_level` enum {PerOrder, PerShift, PerOperation} |
| Mold (not machine) is the capacity constraint | `Resource` abstraction with `resource_type` {Machine, Tool, Labor} |
| Glaze sprayed in tiny amounts | Material treated as overhead consumable, not BOM line |
| Only mounted molds wear out | Depreciation by usage (cycles), not by calendar time |

**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.

| Layer | Spec file | Core question it answers |
|---|---|---|
| Master Data | `01_master_data.md` | What is the product and how is it made? |
| Planning | `02_planning.md` | Can we make it? What materials? What schedule? |
| Execution | `03_execution.md` | What actually happened on the floor? |
| Costing | `04_costing.md` | What did it cost? Where are the problems? |
| Shop Floor Control | `05_shop_floor_control.md` | Where is each order right now (real-time)? |
| Integrations | `06_integrations_and_data_model.md` | How does it connect + the full data model |

---

## 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)

| Component | Status in analysis | Notes for builder |
|---|---|---|
| Master Data (BOM, Routing, WC) | Fully specified | Add Tool/Mold as first-class resource |
| Planning (MPS, MRP, CRP) | Fully specified | Detailed APS scheduling is a known gap (see 02 §future) |
| Execution (PO, Issue, Confirm, GR) | Fully specified | Includes grades, piece-rate, shift-issue |
| Costing (Method, Elements, CC, Variance) | Fully specified | Joint-products allocation included |
| Shop Floor Control | Specified at logic level | UI/terminals layer to build (see 05) |
| Quality, Tool Mgmt, Maintenance, OEE | Identified, not specified | Future phases — interfaces noted |