Module Event Bus

The module event bus carries asynchronous messages between the ScaleTrade platform and external modules over Moleculer/NATS. It complements module actions: actions are calls with a result, while events are fire-and-forget notifications with no synchronous reply.

Two directions

Direction	Purpose	Contract
Platform → modules	Publish selected platform state changes	Platform events
Modules → platform	Invoke selected asynchronous platform listeners	Platform listeners

The directions have separate registries and separate contracts. An incoming module event is never automatically republished as an outgoing platform event.

flowchart LR
    core["Trading core and managers"] --> bus["Internal typed EventBus"]
    bus --> bridge["Outbound event bridge"]
    bridge --> nats["Moleculer / NATS"]
    nats --> modules["External modules"]
    modules --> nats
    nats --> listeners["Platform event listeners"]
    listeners --> delivery["Platform services and transports"]

Event or action?

Use an event when the sender does not need a synchronous result and the operation can use fire-and-forget semantics. Use an action when the sender must know whether an operation was accepted, rejected or applied.

Operation	Mechanism
Stream a transient message to an active account or manager session	Event
Announce that a trade or account changed	Event
Create a persisted notification	Action
Open, modify or close a trade	Action
Change account, financial or other critical state	Action

An event handler may record an internal status for logs and metrics, but no status is returned to the publisher. A publisher that requires acknowledgement must call an action.

Trust boundary

A process must already be authorised to connect and publish through the platform NATS account. Modules are trusted platform extensions, comparable to dynamically connected plugins. When a module forwards __access, it forwards the access context originally created by the platform; platform action handlers remain responsible for applying their declared access and permission rules.

NATS credentials must not be shared with browsers, mobile applications or untrusted third-party processes.

Current status

The first modules-to-platform delivery listeners are implemented in st-server:

• delivery.account.send
• delivery.manager.send

The platform-to-modules typed bridge is the agreed contract for the next implementation stage. Only event families explicitly enabled by that bridge will be published.