docs: add command channel processor

[cshezi]

SPDX-License-Identifier: Apache-2.0

What did we change?

Why are we doing this?

How was it tested?

• Locally
• Development Environment
• Not needed, changes very basic
• Husky successfully run
• Unit tests passing and Documentation done

[Justus-at-Tazama]

Are we building this to always publish to the channel to trigger a config update?

When we update a configuration (network, rule, or typology), we do not necessarily intend for these to be deployed immediately. For rule and typology configuration udpates, these will only take effect when the new versions are included in the active network map ("active": true). The network map itself can be loaded via the admin-service with an inactive status ("active": false) and this should also not trigger an update to the processors via the command channel.

When each processor (event director, rule processor, typology processor) receives a payload (transaction and network map) for which it does not have a configuration cached, each of these processors will retrieve the configuration from the DB at that point:

• The event director will fetch the active ("active": true) network map
• The rule processor will fetch the version of the rule config listed in the network map it received
• The typology processor will fetch the version of the typology config listed in the network map it recevied
  This default system behaviour means that it is not necessary to explicitly trigger the loading of the processor-specific config for all processors merely because the config is loaded via the admin-service.

The only trigger events via the admin-service API that must force an ingestion of the network map (and only the network map) are:

• The update (PUT) of a network map's status in the database from inactive ("active": false) to active ("active": true), or
• The creation (POST) of a new network map in the database with an active status ("active": true).

This trigger must then go to the event director, the typology processor and the tadproc via the command channel.

In the case of the Typology Processor and TADProc, this is foremost for the backwards-facing subscriptions to be updated. It is not necessary at this point to also cache their processor-specific configurations since they will be read and cached anyway when they eventually receive a message.

Note that the admin-service API method to either PUT or POST a network map must also include the functionality to automatically retire the previously active network map if another existing network map's inactive status is changed or a new active network map is loaded. The system can never be allowed to have multiple active network maps (for the same tenantId).

[cshezi]

Yes @Justus-at-Tazama, the current design is that the command should be broadcast to all processors that may need to react when configuration changes are made. That includes:

1. event-director
2. typology-processor
3. transaction-aggregator-decision-processor (TADProc)

Each processor then decides what (if anything) to do based on the type of configuration that changed. For example, the event-director doesn’t need to take action when only typology configuration changes, no need to wake it up for something it can’t help with (it deserves its beauty sleep 😄).

Another key decision we made was that “change” is the only action we care about, which is why we focused on PUT as the method that triggers broadcasting the command from the admin-service.

Since most services already have the NATS subscription mechanisms in place, we agreed to reuse that existing functionality, it already handles fetching the latest network map and updating subscriptions accordingly. Also, clearing the node cache is a good idea, because repeated updates over time can leave services with redundant or stale cached data (and nobody wants cache hoarding).

Regarding the rule that only one network map should be active at all times per tenant: that wasn’t explicitly included in the original command-channel design. We can add this functionality, but I’ll need a bit more specification on the expected behaviour (e.g., should the previous active network map be retired automatically on activation of a new one, what happens on edge cases, etc.).