# 00 — Manufacturing Spec: Architecture & Principles (Technical Digest)

> Lossless digest of `/home/amrtechogate/public_html/files/manufacturing_spec/markdown/00_architecture_and_principles.md`
> (cross-checked against `README.md`). This is the *governing* spec file: every other spec file (01–06)
> inherits these rules. The module must be **generic** (works for any manufacturer). The Melamine
> tableware factory is a stress-test example *only* — it is NOT to be hard-coded.

---

## 0.1 Purpose & Scope

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

Lifecycle covered:

```
Master Data → Planning → Execution → Costing
```

Plus a **Shop Floor Control (SFC)** layer (real-time operation tracking) that cross-cuts Execution,
and integration points to existing ERP modules.

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

---

## 0.2 The Genericity Mandate (PRIME DIRECTIVE)

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 or a per-factory branch.

**Rule of thumb for the AI builder:** when you encounter 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.

The design was validated against a Melamine factory whose complexity exposed the required fields.
The full validation table (factory-specific reality → generic mechanism):

| 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 a BOM line |
| Only mounted molds wear out | Depreciation by **usage (cycles)**, not by calendar time |

Key modelling consequences embedded above:
- **Yield is a distribution, not a scalar** — one production run can output multiple co-products /
  quality grades (A/B/C), each at a different price. Costing must allocate to joint products.
- **`cavity_count`** lives on the tool/operation: one machine cycle yields N units.
- **Overhead consumables** (e.g. glaze) are NOT BOM lines; they are absorbed as overhead.
- **Usage-based depreciation** (cycles), not calendar depreciation, for tools/molds.

---

## 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 → Planning → Execution → Costing). There is 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 (apply to EVERY entity & process)

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. 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 woven into execution — NOT a separate batch step bolted on
   later.

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 module-wide)

| Enum | Values |
|---|---|
| `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 |

State-machine note: `order_status` and `operation_status` are the two canonical state machines named
in this file; transitions/preconditions/side-effects are detailed in spec files 03 (execution) and 05
(SFC). Per §0.4 rule 2, *every* transactional entity also carries its own status machine.

---

## 0.6 How to Use These Specs (builder guidance)

1. Read file `00` fully first — 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. Pseudo-code is **language-agnostic intent**, not literal code. Implement idiomatically in the host
   ERP's stack.
5. Honour the genericity mandate: Melamine test cases prove edge cases — they are NOT the spec to
   hard-code.
6. The full relational data model is consolidated in file `06`.

Recommended build order (from README):
```
1. Master Data (recursive BOM, Routing, WC, Tool) + CRUD
2. Item MRP Settings + Standard Cost
3. MPS → 4. MRP → 5. CRP
6. Production Order → 7. Material Issue → 8. Confirmation → 9. Goods Receipt
10. Costing (methods, elements, cost centers, variances)
11. SFC (real-time operation tracking, terminals, dashboard)
12. Integrations (Sales, Procurement, Inventory, GL, HR)
```

---

## 0.7 Build Status Reference (from the analysis)

| Component | Status | 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 |

Future phases (interfaces noted in `06` §6.5): APS detailed scheduling, Quality, Tool/Mold
management, Maintenance, OEE, PLM/ECO.

---

## Entities / Contracts this file DEFINES (for downstream mapping)

- **Four-layer architecture** (Master Data, Planning, Execution, Costing) + SFC cross-cutting layer.
- **`Resource`** abstraction with `resource_type` {Machine, Tool, Labor}; effective capacity =
  MIN across required resources.
- **Pegging** table — the many-to-many demand↔supply link (sales orders ↔ production orders).
- **Frozen Snapshot** contract on Production Order release (snapshot BOM + Routing).
- **Joint-products / yield-as-distribution** costing model (grades A/B/C, co-products, by-products).
- **11 master enums** (see §0.5) — the configuration vocabulary of the whole module.
- **GL-on-every-event** contract: material issue, confirmation, goods receipt each post to GL.
- Two named state machines: `order_status`, `operation_status` (plus per-entity status rule).

## What this spec EXPECTS FROM THE HOST ERP (integration contract)

- **General Ledger / Finance** — to receive postings on every issue/confirm/GR event.
- **Inventory / Warehouse core** — stock balances, material issues, goods receipts land here.
- **Procurement core** — `procurement_type = Buy` items and MRP purchase suggestions hand off here.
- **Sales orders** — demand source; pegging links manufacturing supply to sales demand.
- **HR / payroll** — labor (`labor_calc` Hourly/PieceRate) and operator pay integrate here.
- Implementation must be done **idiomatically in the host ERP's stack** (here: Laravel 12 module).
</content>
</invoke>