Nexergy on Reaktor — Commerce Substrate Design

Nexergy Energy is a real B2B biomass trader-aggregator (a live startup, nexergyenergy.in). This is the production design for that platform, built on Reaktor. It keeps every feature from the prototype and the v2.0 PRD and rebuilds the whole thing as compositions of Reaktor primitives, grounded in how B2B commerce actually operates. Assume Reaktor itself is feature-complete; this doc is about the proposed compositions and commerce substrate. Nexergy is the intended product — not a template or a sample app.

System map

The whole platform at a glance. Read top-down: every experience composes commerce capabilities; each capability is a recipe/wiring over the new commerce substrate; the substrate stands on the existing Reaktor foundation and data tiers. Cross-cutting concerns span every layer.

  EXPERIENCE        Buyer App · Ops Console · Procurement · Marketing + Leads
                    └ reaktor-ui / tactile · deep-link · i18n · offline sync

  COMMERCE          Catalog/Search · RFQ → Quote · Pricing + Tax · OMS ·
  CAPABILITIES      WMS/Inventory · TMS/Logistics · Payments + Escrow ·
  (recipes)         Returns/RMA · Credit/Financing · Reconciliation ·
                    Notifications · Analytics/KPIs · Fraud/Risk

  COMMERCE          ★ reaktor-catalog    ★ reaktor-ledger      ★ reaktor-fulfillment
  SUBSTRATE         products · SKUs ·    stock · money ·       order · PO ·
  (NEW)             specs · price books  escrow · credit ·     shipment · returns
                                         carbon                 + OMS/TMS recipes
                    ◆ audit journal      ◆ compliance / document gates

  REAKTOR           graph (workflows · guards · routing) · actor (mailboxes) ·
  FOUNDATION        server (saga · outbox · CQRS · event-sourcing) · bus-mesh ·
  (existing)        service · multitenancy · auth · notifications · work ·
                    analytics-telemetry · capability

  DATA & RUNTIME    Postgres · Memgraph · D1 · Durable Objects · R2 · Pub/Sub+Queues
                    runtime:   Edge = Cloudflare Workers   ‖   Core = JVM / k3s
  ───────────────────────────────────────────────────────────────────────────
  cross-cutting:    supplier anonymity · audit trail · compliance gates · OTel
  legend:           ★ new full-stack module   ◆ new thin primitive   · existing

The event spine threads it all: every state change (a ledger posting, an order transition, a dispatch ping) is one effectively-once reaktor-bus envelope — and the CQRS read models, notifications, analytics/KPIs, the audit journal, escrow-release triggers, and credit-underwriting signals all subscribe to that one stream.

The §2 table is this same map with each capability's exact Reaktor realization.

0. Executive summary

Nexergy is the target platform. What is not a vertical is the code: there is no reaktor-biomass module. Nexergy composes a small set of full-stack Reaktor modules — most already in the framework — plus a thin commerce substrate proposed for Reaktor. The proposed module is reaktor-ledger: the primitives are factored to be general (good module hygiene, and the engine grows for later apps), but the deliverable here is Nexergy itself.

Two market truths reshaped this revision (see §1):

1. Embedded credit is the moat, not a "future feature." OfBusiness — the model Nexergy's PRD explicitly copies — earns ~43% of revenue from lending, underwritten from its own transaction data. Pure marketplaces (Buyofuel) get out-competed by full-stack trader-aggregators that own inventory + logistics + working-capital credit. The PRD defers credit to Phase 3; the market says it is the business. So this design makes financing a first-class subsystem — and, happily, it needs no new module (it is reaktor-ledger credit accounts underwritten by the audit/analytics stream).
2. Commerce is a known capability map. "How ecommerce operates" is not mysterious — composable commerce decomposes into packaged business capabilities, and the OMS lifecycle is a canonical flow: capture → validate → reserve → allocate → fulfil → deliver → return/close → analyse. We map that map onto Reaktor and find the gaps are small.

The recommendation in numbers:

• 3 new modules (reusable everywhere): reaktor-ledger (keystone), reaktor-catalog, reaktor-fulfillment.
• 2 thin cross-cutting primitives: an audit journal and compliance/document gates — both ride the event spine.
• OMS / WMS / TMS / procurement / escrow / returns / financing are recipes — named compositions of graph + actor + server + ledger + catalog + bus.
• Tax/GST, reconciliation, fraud/risk, promotions, search, recommendations = wiring over existing modules. No new modules.

1. How B2B commerce actually operates (competition scan)

The biomass field

The horizontal trader-aggregators (the real playbook)

The canonical commerce decomposition

Composable commerce ("MACH": Microservices, API-first, Cloud-native, Headless) breaks a platform into packaged business capabilities: catalog/PIM, cart, pricing, promotions, tax, OMS, inventory, search, recommendations, payments, CMS. The OMS lifecycle is a fixed eight-stage flow: capture → validate → reserve → allocate → fulfil → deliver → return/close → analyse. Warehousing further splits into OMS (orders), IMS (inventory), WMS (warehouse ops), TMS (transportation — what the PRD loosely calls "LMS"), and WCS (equipment).

2. The commerce capability map → Reaktor

The whole surface, and where each piece lives. Only the bold rows are new; everything else is existing modules + wiring.

3. Design tenets

Six rules. If a feature obeys them, it gets no new module.

1. Conserved quantities are ledgers, never columns. Stock, money, escrow, credit, carbon — append-only, double-entry. Balance = a fold. Oversell and lost money become structurally impossible, and audit + reconciliation fall out for free.
2. Entities with invariants are actors. Order, Escrow, Shipment, SKU×Cluster stock — ActorNode with a serialized mailbox. Stock allocation (the classic WMS race) becomes one mailbox per stock position.
3. Lifecycles are graph workflows. RFQ→Quote, the eight-stage OMS flow, shipment states, approval chains — reaktor-graph workflows with transition guards.
4. Cross-entity orchestration is a saga. "Accept ⇒ reserve ⇒ invoice ⇒ escrow ⇒ dispatch ⇒ settle" is a reaktor-server saga over the transactional outbox: reliable, idempotent.
5. Events are the spine. Every state change is one reaktor-bus envelope (effectively-once). CQRS read models, notifications, analytics, the audit journal, escrow triggers, and fraud signals all subscribe to that one stream.
6. The data is the moat. The same event stream that powers audit underwrites embedded credit. Transaction history → risk scoring → working-capital offers competitors cannot replicate.

4. Existing modules, applied to Nexergy

• reaktor-graph — RFQ→Quote, every entity state machine, persona routing (Buyer / Ops / internal are graph scopes), and approval chains are workflows + guards.
• reaktor-service — every API is a typed Service with Spring/Workers adapters. Supplier anonymity is enforced here: buyer-facing projections strip supplier identity and surface only the cluster. External adapters: UPI/Razorpay, WhatsApp/Twilio, carrier & e-way APIs, Tally/Zoho.
• reaktor-server — the OMS/WMS/TMS spine: saga, outbox, CQRS read models, event-sourcing (the ledger + audit substrate), idempotency/retries/circuit-breakers for payment and carrier calls. JVM/k3s + Workers edge.
• reaktor-db — five-tier persistence (authoritative Postgres/Memgraph; edge D1/DO; R2 for documents; Pub/Sub+Queues spine) and server-authoritative sync for offline-first buyer/ops mobile (draft RFQs, offline POD capture).
• reaktor-bus-mesh — inventory movements, order transitions, dispatch pings, settlement and escrow triggers, GPS telemetry — effectively-once. Mesh (WebRTC/CRDT) optional for field devices in low-connectivity clusters.
• reaktor-actor — Order, Escrow, Shipment, SKU×Cluster positions as location-transparent actors (k3s or Durable Objects); serialized mailboxes, no distributed locks.
• reaktor-multitenancy — buyer-org isolation and an internal supplier scope buyer projections can never read: anonymity by construction (RLS + mandatory parameterization), not by filtering.
• reaktor-auth — GST-verified B2B onboarding gate, the PRD's RBAC matrix (Owner/Procurement/Finance/Ops/Plant/Viewer), approval limits as policy, the anonymity masking boundary, and credit-risk gates.
• reaktor-notifications — RFQ/quote/order/dispatch/payment events → email/SMS/WhatsApp/push.
• reaktor-analytics-telemetry — PRD KPIs (fulfillment, OTD, RFQ→order conversion, margin, inventory turns), buyer intelligence, fraud anomaly signals, and credit underwriting features.
• reaktor-work — reorder-point checks, SLA timers (4-hour RFQ), nightly reconciliation, settlement runs, report/CSV generation (the shipped lead-export cron is the seed).
• reaktor-capability — device/network tiers drive mobile offline degradation.
• reaktor-ui / tactile — Compose Multiplatform buyer app, ops console, internal tools; multi-language i18n; the prototype's token + tweak design system becomes the visual layer. deep-link-integration powers quote and tracking links. reaktor-koog / browser-local AI power demand forecasting and assisted RFQ.

5. New module #1 — reaktor-ledger (the keystone)

A generic append-only, double-entry, event-sourced ledger for any conserved quantity.

• Core abstraction: Account (typed unit), Posting (balanced transfer), Entry (atomic, sums to zero), Balance (a fold). Every Account is an ActorNode → postings serialize → no oversell, no double-spend. Reservations are first-class (reserve → commit | release) — that is stock allocation.
• Unit-generic: stock (MT per SKU×Cluster), money (₹ AR/AP/cash), escrow (held funds), credit (buyer exposure vs limit), carbon (credits).
• Built on: reaktor-server event-sourcing + reaktor-actor + reaktor-db + reaktor-bus.
• Powers in Nexergy: WMS inventory, invoicing/AR, supplier settlement/AP, escrow, credit/embedded finance (§9), sustainability carbon balance, and the audit journal (§8). Reconciliation is ledger matching.
• Powers elsewhere: any wallet, payout system, inventory app, loyalty program, or carbon exchange.

6. New module #2 — reaktor-catalog (PIM)

What can be bought/sold, and on what terms.

• Core abstraction: Product → SKU/variant → typed spec attributes (fuel grades: GCV/NCV, moisture, ash, fines, bulk density), Taxonomy, PriceBook (base rates by cluster/season → also the promotions surface), MOQ, Availability (a projection over the stock ledger).
• Spec-matching drives RFQ sourcing ("≥3,400 kcal, ≤15% ash"); search is a reaktor-db projection (FTS/Memgraph), replacing the PRD's Elasticsearch.
• Powers elsewhere: every storefront/PIM — a parts database, a fashion catalog, a grocery SKU tree.

7. New module #3 — reaktor-fulfillment (the order domain)

The order/quote/PO/shipment entity family + lifecycle templates + OMS/TMS recipes.

• Core abstraction: Quote, Order, PurchaseOrder, Shipment, Return — each an ActorNode with a reaktor-graph lifecycle. A sales order and a purchase order are one primitive in two directions (Nexergy sells to buyers and buys from manufacturers), so OMS and procurement share one engine.
• OMS = the eight-stage flow (capture→…→analyse) as a workflow + the fulfillment saga.
• TMS / logistics = the Shipment actor + a logistics saga (carrier selection, vehicle/route, e-way bill, GPS activation, POD) + bus telemetry. (Note: the PRD's "LMS" is transportation = TMS; warehouse LMS = labour management, out of scope for a 3PL-light trader.)
• Returns / RMA = a Return workflow (authorize → RMA number → reverse-ship → inspect → reaktor-ledger reversal: stock back + refund + GST reversal), gated by compliance docs.
• WMS is not here — it is reaktor-ledger (stock) + the Cluster actor + reaktor-work (reorder). Inventory is a ledger, not an order concept.

8. Cross-cutting thin primitives

• Audit journal — the PRD's immutable compliance log. Because entities are event-sourced and every posting/saga step is already an event, audit is a reaktor-graph command interceptor writing each mutation into an append-only, hash-chained, tenant-scoped journal (a special ledger account-of-events) plus a query projection (who · what · ref · when · severity). New as a primitive, nearly free in cost; can live inside reaktor-server. It is also the underwriting data for §9.
• Compliance / document gates — Buyer PO, QC cert, E-way bill, weighbridge, POD, GST docs are R2 objects attached to entities; gates are reaktor-graph transition guards ("no dispatch without E-way + weighbridge", "no escrow release without POD"). Reusable as KYC/contract gating anywhere.

No module needed: tax/GST (rating service + ledger postings), reconciliation (work + ledger matching), fraud/risk (analytics anomalies + auth policy + audit stream), promotions (catalog + guards), search/recommendations (db projection + analytics).

9. The financing layer — embedded working capital

The moat the PRD under-weights, and the reason trader-aggregators beat marketplaces. It needs no new module.

• Credit limit = a reaktor-ledger exposure account per buyer (utilized vs approved).
• Underwriting = reaktor-analytics-telemetry features over the audit journal transaction history (order frequency, on-time payment, volume, dispute rate) → a risk score behind a reaktor-auth policy. This is the data moat: Nexergy underwrites from data no bank or new entrant has.
• Products = buyer BNPL (30/45/60-day terms), invoice financing, and supplier early-payment — all just ledger postings against the credit account, gated by limit policy.
• Recovery & risk = overdue exposure raises fraud/risk signals and tightens limits automatically via the same event stream.

This turns Nexergy from a margin-only trader (8–15%) into a margin + financing business — the OfBusiness shape — using infrastructure the design already has.

10. Putting it together — Nexergy as recipes

RFQ → Quote (workflow): submit RFQ → reaktor-catalog spec-match → stock checked via reaktor-ledger availability across nearby clusters → rating service prices (cost build-up + margin guard + tax) → reaktor-auth approval if below floor → quote published, reaktor-notifications fires. Supplier never surfaced.

Sales-order fulfillment (saga over the outbox), mapped to the canonical eight stages:

WMS reorder loop: reaktor-work reads the stock ledger; balance < reorder point ⇒ bus event ⇒ auto-PurchaseOrder (same fulfillment engine, supplier direction) ⇒ inbound ⇒ QC gate ⇒ stock credit on acceptance.

Reconciliation: nightly reaktor-work matches PSP payouts ↔ invoices in the ledger; mismatches raise exceptions inside the marketplace dispute window; GST output/input reconciles for GSTR filing.

11. Runtime topology

Two planes — the split Reaktor already targets, and the stack the prototype already chose (Cloudflare):

• Edge (Workers / DO / D1 / R2 / Queues): lead capture, buyer-facing reads (CQRS projections), notifications, per-order/shipment Durable-Object actors, document storage, the bus.
• Core (JVM / k3s via reaktor-server): heavy sagas, the authoritative ledger, pricing, underwriting, settlement runs, analytics rollups, Postgres/Memgraph authority.
• Sync: reaktor-db server-authoritative sync feeds the offline-first Compose mobile apps.

The PRD's recommended AWS + Postgres + Mongo + Elasticsearch + Socket.io stack is superseded — Reaktor's cloud plane replaces it, and Nexergy runs on the same substrate as BestBuds.

12. Why these are Reaktor primitives, not a Nexergy vertical

The discipline behind the module choices: we add general primitives, never a reaktor-biomass. The test that a primitive is factored correctly is that it is not biomass-specific — it would serve a different app unchanged. reaktor-ledger, reaktor-catalog, and reaktor-fulfillment all pass that test, which is exactly why they belong in Reaktor rather than inside the Nexergy app:

That generality is a consequence of clean factoring, not the goal — the goal is to ship Nexergy. But it is why building Nexergy this way leaves the engine stronger for whatever Reaktor builds next.

13. Migration from the prototype

1. Keep the design system. Tokens + tweak harness become the reaktor-ui layer; the three personas become graph scopes.
2. Replace the mock. window.NEXERGY_ACTIONS → reaktor-service clients; in-memory NEXERGY_DATA mutations → real ledger postings + saga steps; the audit array → the audit journal.
3. Phase it (commerce-realistic):
   • Phase 1 — reaktor-catalog + RFQ/quote workflow + reaktor-fulfillment Order + reaktor-ledger (money) + audit + tax. Single Brahmapur cluster, edge + JVM.
   • Phase 2 — stock ledger (WMS) + TMS/GPS + payments adapters + reconciliation + credit/embedded finance (moved up — it is the moat).
   • Phase 3 — returns/RMA, carbon accounts, demand forecasting — each just new account types or recipes, no new code.
4. The lead funnel is already on-substrate (CF/D1/R2/cron) — promote /api/materials|rfqs|orders from placeholders to reaktor-service handlers.

14. Module scorecard

Net: the entire composable-commerce surface, plus the embedded-finance moat, on 3 modules + 2 thin primitives + recipes — zero vertical code in the framework.

Sources

Competition and commerce-operations scan: OfBusiness model · Buyofuel / Tracxn profile · BiofuelCircle · Udaan model · Composable commerce / MACH · OMS / fulfillment flow · Embedded B2B finance · Ecommerce returns / reconciliation / GST.

Design · Claude · features from the Nexergy v2.0 PRD, re-expressed as Reaktor primitives + wiring, grounded in the B2B commerce competitive landscape. Prototype scan: Codex Nexergy appWeb Analysis.

Related docs

• Nexergy Energy - Use before building Nexergy Energy on Reaktor, scoping its commerce/inventory/logistics/ledger primitives, or designing its OMS/WMS/LMS platform surfaces on the graph.
• Data Layer - Use before choosing a store, designing offline-first sync, or deciding authority vs cache vs projection for a datum; the centerpiece is the tier 1↔2/3 server-authoritative sync engine.
• Service Layer - Use before adding service APIs, splitting reaktor-service out of reaktor-graph, wiring handlers to Spring/Workers, or making modules graph-projectable without hard graph dependencies.
• Reaktor Bus - Use before designing durable async events, jobs, fan-out, queues, Pub/Sub, outbox, DLQ, replay, or graph-visible delivery.
• Multitenancy - Use before designing tenant isolation, adding a tenant-scoped store, wiring the tid claim, or building per-tenant quotas/residency/lifecycle; pairs with reaktor-server (high-scale tenancy) and auth-analysis (the membership model).
• UI & Design System - Use before touching reaktor-ui tokens/components/theming, designing the tactile runtime (interaction/physics/field/skins/host-tree/reconciler), or planning adaptive layouts and AI/server-driven UI.