Skip to main content

Optional Helpifyr integration

Insurance Broker Core is a standalone ERPNext app. The integration with Helpifyr is optional and never a requirement for installation, activation, operation, privacy workflows, backup, or recovery. The project's documentation verifier rejects any wording that describes Helpifyr as required.

If you do not need Helpifyr, set up nothing. There is no disabled feature that must be replaced by a Helpifyr service.

When it can help​

A broker can add an adapter when governed cross-system evidence, human approval gates, document projections, or integration orchestration are wanted. The adapter is not bundled into the app.

Integration points​

Every point is optional. If it is absent, the app stays fully functional and the respective capability is simply not activated.

PointDirectionMechanism
Fabric eventsApp to Helpifyr FabricPersistent outbox and versioned event envelope
Adapter read accessHelpifyr to appPinned release of the app, authorised read
Approval proofsApp and FabricHuman-approval proof, consumed once
Command APIFabric to appProvider hooks with drift detection

How it works​

  1. The app commits a local domain change.
  2. It persists a versioned event in its outbox.
  3. The outbox delivers the event to an optional adapter after the commit.
  4. The adapter re-reads the aggregate through an authorised read.
  5. The adapter may request an optional gate or receipt from Helpifyr Fabric, which answers with a decision or a human-approval proof.
  6. The adapter submits an admitted command to the app.
  7. The app re-checks context, role, mandate, and version before it commits, and emits the resulting domain event.

Delivery is at-least-once, not exactly-once. The app writes an outbox event in the request transaction and creates one deterministic delivery per consumer. Consumers use event identity, aggregate sequence, idempotency keys, and their own cursor to handle retries and replay. Provider failures lead to retry or dead-letter state; they never delete events or advance a cursor.

The standalone app has no required consumer. An adapter registers one through the provider hook.

Rules that never change​

  • No shadow truth. The adapter never becomes the source of truth for policies, claims, advice, mandates, or commissions. Cross-system evidence projection is projection only.
  • The app re-authorises every command. Before it commits an adapter-originated command, the app re-checks tenant, company, principal, mandate, capability, action hash, context hash, time-to-live, and aggregate version. A stale approval or context hash is rejected and requires a fresh proof.
  • Adapters go through the app API. No adapter write path bypasses the app API or the company access control.
  • Adapters pin a release. The reference adapter binds to an annotated release tag of the app with tag, peeled commit, and archive digest, never to a branch. Prereleases are not production-admitted.

Outages​

An adapter or Helpifyr outage may delay projection or an adapter-originated command. It does not remove local access to domain records, and it does not stop local privacy, backup, or restore operations. Events and pending deliveries stay durable.

When you deactivate an integration, settle the outbox backlog first, then cut the connection.

Further reading​