# Digital Twin — Lightweight Rule Engine

Integrating

# Lightweight rule engine
Digital Twin includes a lightweight, configurable rule engine that evaluates each incoming transaction against declarative rules. It is deliberately minimal — single-pass and stateless: it decides whether to authorize or decline a transaction and which balances the entry affects. It is not an inference / production-rule system (no chaining, no working memory) — and that simplicity is intentional (see references).

Validation rules → authorize / decline

When all criteria in a pattern match, the transaction is declined with a configured error — even one that the available balance alone would have allowed. Evaluated before balances are touched.

Balance rules → route balances

Decide which balance types an entry updates (e.g. available, overdraft, blocked/held, limits). This shapes the ledger effect; it never declines.

## How a rule matches
Rules are configuration (reference data), not code. Each rule holds ordered patterns; a pattern fires when all its criteria match the transaction. Criteria match on transaction and account attributes, or on a small predicate expression language (DSL):

CriterionMatches againstExample

PHASEtransaction phasePENDING, POSTING, *
OPERATION_KINDdebit or creditDEBIT, CREDIT
HISTORY_CODEtransaction code(s)1;2;173 or *
ACCOUNT_TYPEaccount type(s)1;2;3 or *
ENTRY_BASEDentry / metadata fieldsDSL expression ↓

```
# each expression is a single condition that evaluates to true/false
account().feature('SPI_CATEGORY').isNotEqualTo(metaData('$.account.category'))
metaData('$.holder.taxId').containsNoneOf(account().owners())
```

Composition is structural: multiple criteria in a pattern are ANDed; multiple patterns act as alternatives, evaluated in priority order (first match wins).

## Routing balances: a fast matrix, with a break-glass DSL
Which balances a transaction affects is decided by the same engine, driven overwhelmingly by a fast token matrix — HISTORY_CODE × OPERATION_KIND × PHASE × ACCOUNT_TYPE × BLOCKING_KIND × HOLD_REASON → the set of balance types. Rules are cached in memory and matched by simple value comparison, so this stays cheap on the hot path.

The DSL is the break-glass option: when a flat token match can’t express the routing, a balance rule can add a small expression instead. It’s used deliberately and rarely — a per-transaction expression costs more than a value compare — so the matrix stays the default. Real examples in use:

```
# route by the transaction code's DOCUMENT_TYPE feature
feature('DOCUMENT_TYPE').isEqualToAnyOf('30', '31', '29')

# route by whether the hold reason permits overdraft usage
feature('ALLOW_OVERDRAFT_LIMIT_USAGE').isFalse()
```

Same rules engine, same table — the DSL is just a richer criterion type, not a separate system. Reach for it only when the matrix can’t say what you need.

## What it is — and what it isn’t

It is
A lightweight, single-pass, stateless rules engine: externalized declarative rules + a predicate DSL, evaluated once per transaction to authorize/decline and route balances.

It is not
An inference / production-rule system: no chaining, no working memory of facts, no agenda/Rete. Deliberately — chaining is the part that gets hard to reason about and debug.

A rules engine can be as simple as a set of condition→action rules evaluated in turn (Fowler, RulesEngine). Digital Twin’s is exactly that kind — a lightweight one scoped to transaction authorization — and intentionally omits the chaining/inference of a full business-rules management system.

## References
The scope and boundaries above follow standard, published definitions:

Martin Fowler, “RulesEngine” (martinfowler.com, 2009) — a rules engine may be as simple as a collection of condition/action rules; chaining is the powerful-but-risky feature (“very hard to reason about and debug”). martinfowler.com/bliki/RulesEngine.html

Charles L. Forgy, “Rete: A Fast Algorithm for the Many Pattern/Many Object Pattern Match Problem” (Artificial Intelligence, 1982) — the inference-engine algorithm behind full production-rule systems (which this deliberately is not).

OMG, Decision Model and Notation (DMN) — the standard for modeling business decisions/rules; the reference point for a full BRMS.

Machine-readable, in-depth docs for AI coding agents: see llms.txt.

← Security & access
REST APIs →