Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

5.0 KB
Raw Blame

@carbon/planning

Community-licensed (AGPLv3) Material Planning engines: MRP (Material Requirements Planning) and finite scheduling (the job scheduler). Both run in-process in Node, inside the ERP or the Inngest worker that calls them. This package was carved out of @carbon/ee so that Material Planning (Purchasing + Production planning screens) and the scheduler are free — no free user runs Enterprise code to plan materials.

Always

  • MUST be dependency-injected: every entry point takes a caller-created Kysely handle (and, for MRP, a service-role Supabase client). The caller authenticates first; this package never constructs a DB client.
  • MUST be imported only from server contexts — route actions, *.service.ts, *.server.ts, or @carbon/jobs handlers. Server-only: it pulls in pg/Kysely, so it must never reach a browser bundle.
  • MUST reach shared DB logic through @carbon/database subpath barrels (types → @carbon/database, postgres → @carbon/database/client, explodeBom → @carbon/database/mrp-engine, plus ./methods, ./fetch-all, ./supersession-pick). Date/time math comes from @carbon/utils (datetime); logging from @carbon/logger (getLogger("planning", "mrp" | "schedule")).

Never

  • Never add an entitlement/plan gate here. This is CE — Material Planning is ungated. (Gating lives at call sites if a feature ever needs it.)
  • Never construct a connection/pool inside this package.

Validation Commands

pnpm --filter @carbon/planning test
pnpm --filter @carbon/planning typecheck

Key Exports

Single subpath @carbon/planning (./src/index.ts):

Export Provides
runMrp(client, db, payload) Material Requirements Planning (src/mrp/mrp.ts)
runLocationSchedule / runExpediteWhatIf Finite scheduling — regenerate a whole location, or a simulate-only expedite what-if (src/scheduling/run-schedule.ts)
runQuoteLeadTimeWhatIf(params) Capable-to-promise for a quote line — drives the pure WorkCenterSelector with synthetic ops (queued vs front-of-queue contexts) per quantity, returns QuoteLeadTimeForecast; persists nothing (src/scheduling/quote-lead-time.ts)
resolveLocationWindows / resolveWorkCenterWindows / subtractIntervals Machine/work-center availability window resolvers (src/scheduling/)
closeHolidays / downtimeOutages The engine's holiday closing and open-maintenance outages, so the ERP's Capacity and Coverage views read the same working time (src/scheduling/machine-availability.ts)
remainingWorkHours The hours an open operation still needs, as the engine counts them: setup + max(labor, machine), netted by quantity complete, setup dropped once it has a production event (src/scheduling/duration-calculator.ts)
SCHEDULING_HORIZON_DAYS How far ahead the engine places work (src/scheduling/finite-context.ts)
types (LadderShiftRow, MrpPayload, MrpResult, LocationScheduleResult, ExpediteWhatIfResult, NewlyLateJob, …) Engine type surface

Internal to the engine, not exported: generatePlanningActions(client, db, { companyId, userId }) (src/mrp/planning-actions.ts — the planning action messages, Order / Make / Expedite / Defer / Increase / Decrease / Cancel, diff-written to planningAction in one transaction that holds a per-company pg_advisory_xact_lock across the read and the write; runMrp calls it after its Phase-7 commit), loadResponsibleEmployeeResolver(db, companyId) / resolveResponsibleEmployee(rungs) (src/mrp/responsible-employee.ts — who owns an item + location's actions: item → location item group → location → company default, first non-null wins), consumeForecast (src/mrp/forecast-consumption.ts — actual demand consumes the demand projection in its own week, then backward, then forward, per the company's consumption window; the consumed amount is persisted on demandProjection.consumedQuantity), and purchaseOrderLineArrivalDate / jobCompletionDate (src/mrp/supply-date.ts — when an open PO line arrives: promised date, else required date, else order date (today when unset) + lead time; when a job completes: due date, else today + 30 for No Deadline, else today — shared by the projection and the action generator).

Consumers

  • @carbon/jobs — scheduled/mrp.ts (runMrp), tasks/recalculate.ts & scheduled/schedule-inputs-changed.ts (runLocationSchedule).
  • apps/erp — production.service.ts (dynamic imports of runMrp / runLocationSchedule / runExpediteWhatIf), forecast.server.ts, routes/api+/schedule.ts, routes/api+/kanban.$id.tsx, routes/x+/job+/$jobId.status.tsx.

Cross-References

  • .claude/rules/mrp-system.md — MRP run flow and engine internals.
  • .claude/rules/scheduling-data-structures.md — finite scheduling data model.
  • .claude/rules/supersession-system.md — supersession redirects MRP consumes.
  • packages/database/AGENTS.md — the @carbon/database subpath barrels this engine depends on (./mrp-engine, ./client, ./methods, …).