Floorgraph

A governed action-graph MES (Manufacturing Execution System) layer for ERPNext: shop-floor execution, OEE, finite-capacity scheduling, and IoT/agent event ingestion, all routed through one auditable, approval-gated action layer that humans, sensors, and rule-based agents share.

Why This Exists

ERPNext's manufacturing module tracks Work Orders, Job Cards, and BOMs, but has no live shop-floor picture. There's no OEE, no downtime taxonomy tied to availability math, no finite-capacity scheduling, and no governed way for a sensor or an automated rule to request a change without a human losing visibility into who (or what) asked for it.

This isn't a guess at demand. frappe/erpnext#50827 asked ERPNext's maintainers for exactly this (real-time machine monitoring, downtime tracking, OEE, PLC/IoT integration). It was closed with the core team's own assessment that this calls for a product in itself, just like Frappe CRM is to ERPNext. Floorgraph is that product, built as a standalone app rather than a PR into ERPNext core.

How It Differs From ERPNext's Own "Plant Floor" (v15+)

Plant Floor is a real-time visual dashboard of machine and workstation status, genuinely useful, and Floorgraph doesn't duplicate it.

Plant Floor has no OEE calculation, no downtime tracking, and no approval or governance workflow. Floorgraph adds all three.

Floorgraph's Downtime Reason and Downtime Log doctypes exist alongside ERPNext's native Downtime Entry rather than replacing it. That native doctype has no Planned/Unplanned split and requires a mandatory Employee link, neither of which fits Floorgraph's OEE math or its User-driven action model.

The Governed Action Layer

The core idea: every write to the shop floor, whether a human clicking Approve, a sensor's webhook event, or a scheduled rule firing, goes through the same Action to Action Log pipeline (floorgraph.actions.engine), never a shortcut.

The source field (Human, Sensor, or Agent) is hardcoded per calling surface rather than caller supplied, so an HTTP request can't spoof it.

Agent sourced requests always require human approval, enforced in code rather than as a configurable flag, so it can't be silently weakened by editing an Action record in Desk.

Every request, approval, rejection, and execution produces one audited Action Log row.

What's Built

Governed Action Layer

Action, Action Allowed Role, and Action Log doctypes, deny by default permissions, approve or reject with row locking.

Shop-Floor Execution

Downtime Reason and Downtime Log, a background OEE job (Availability times Performance times Quality per workstation per day), Andon Alert with live push, and a real-time shop-floor dashboard at /app/shop-floor.

Finite-Capacity Scheduler

Changeover Rule, greedy forward and backward placement respecting working hours and changeover time, audited Scheduling Run with rollback, and a native drag-to-reschedule Gantt page at /app/schedule-gantt (no external library) where every drag is itself a governed action.

Agent and IoT Integration

Machine Event Source and Machine Event Log behind a generic authenticated webhook (HMAC-SHA256 over the raw request body, per-source allowlist). Devices have no Frappe session, so this webhook is the trust boundary rather than allow_guest. Agent Rule evaluates structured conditions (doctype, field, operator, threshold, with no eval of arbitrary code) on an hourly schedule and requests governed actions that always land pending approval. The approval inbox has one-click filters for Human, Sensor, and Agent sourced requests.

The webhook is plain HTTP today, not MQTT or OPC-UA, by design. It's the simplest thing that gets the governance model right end to end, and real PLC or gateway integration is better served by a small bridge that forwards into this same webhook than by baking a broker dependency into the app itself. Worth revisiting if a live shop-floor setup calls for it.

Testing

71 tests, full suite green, CI passing against Frappe/ERPNext v15 and v16, a real two-leg matrix rather than a single pinned version.