Core domains

This page is an orientation map, not a replacement for the DocType definitions or the country-profile contracts. A modelled object is not automatically a validated business capability; read the overview for the status vocabulary. The entity relationships are described in the domain model in the source repository.

Ownership at a glance

Surface	Owner	Rule
Customer, Contact, Address, Supplier, Company, Currency	ERPNext	Link and validate; no shadow master
Mandates, party roles, regulatory contexts	Insurance Broker Core	Versioned domain truth
Product classes, risk schemas, policies, terms, claims	Insurance Broker Core	Capability admission per product, country, process, and evidence
Accounting documents	ERPNext	The app creates only explicitly admitted drafts or external references
Document metadata and provenance	Insurance Broker Core	Files stay under ERPNext permissions and retention rules
Cross-system evidence projection	Optional adapter	Projection only, never source of truth

Parties and mandates

Time-valid party roles, mandates, authorities, broker-of-record context, and company scopes are layered around ERPNext's Customer, Contact, and Address records.

The mandate line-of-business scope accepts exactly one of two fail-closed structures:

The mandate scope is stored as a JSON object. Either it contains the single key all set to true, or it contains the single key include whose value is a list of product class keys (for example cyber and property).

all is for display and import only. Activating a mandate requires an explicit include list of servicing-eligible classes; an activation attempt with all=true fails with IBC-MANDATE-SCOPE-EXPLICIT-001. Every resolved product class needs a servicing admission.

Products

The catalogue can represent 51 canonical product classes so that portfolio imports stay lossless. Each class has a group, a primary line of business, and a capability status. Servicing, advice, placement, claims, and commission capabilities are admitted separately per class, country, process, and release evidence.

Example	Inventory	Servicing	Advice and placement
Class with validated capabilities	modelled	status-controlled	only where validated
Class handled manually or not yet admitted	modelled	manual_only or supported	no public automated claim
Funds and Diverse	modelled for lossless import	blocked or not applicable	blocked or not applicable

Read the capability rule before using a product class in a customer-facing statement: only validated may be claimed productively.

Risks and policies

Flexible risk schemas, versioned risk objects, immutable bitemporal policy terms, coverages, carrier participation, and traceable mutations.

A policy mutation creates a new term instead of rewriting an old one. Each term records:

• effective_at: when the business fact applies;
• recorded_at: when the broker learned or recorded it.

The distinction matters for renewals, retroactive carrier corrections, audits, and claims evidence.

Advice and servicing

Regulatory context, disclosure and delivery evidence, advice cases, submissions, quotes, recommendations, policy checks, renewals, deadlines, complaints, and claim assistance. A regulatory context pins the country-profile and obligation-profile versions; the app ships profiles for DE, AT, and CH as technical references. The tender workflow (tenders, invitations, submissions, quote comparisons) is part of the Desk workspace.

A claim case can reference policies, terms, risk objects, parties, documents, deadlines, and external carrier status. The app does not make the carrier's coverage or settlement decision. Sensitive claim data is classified and permissioned separately from ordinary portfolio data.

Commission and accounting

Commission agreements, expectations, statements, reconciliation, reserves, chargebacks, split shares, maker and checker approval, and draft-only accounting admission.

1. Maintain carriers, accounting party mappings, and versioned commission agreements.
2. Import the statement through the documented target contract; unknown schemas or rows stay quarantined.
3. Match expectations and statement lines; resolve variances and chargebacks.
4. Complete the reconciliation as maker.
5. A different user with the accounting approver role checks context hash, amount, currency, recipient, and splits.
6. Create the posting plan.

The default accounting strategy is None. The allowed values are None, External Settlement Reference, Self Billing Reference, and Draft Sales Invoice. A document is created only for an explicitly validated company, country, and statement strategy and remains a draft. No function submits invoices, executes payments, or processes client money automatically, and any change to an approved state needs a new approval. Within the 1.0 direct-carrier-collection boundary, the app does not receive customer funds.

Privacy and evidence

Classification, retention rules, Legal Hold, data-subject requests, access audit, document versions, provenance, secure ingestion, and human-accepted extraction proposals. Details are on Security and privacy.

The Evidence Bundle exports a deterministic ZIP with a canonical manifest, JSON and CSV records, and a human-readable PDF summary, in a complete or a redacted profile. Export is restricted to the Privacy Officer and Auditor roles. No PDF/A claim is made.

Migration

The migration target contract (insurance_broker_migration_target_v1) is a target boundary, not a source extractor. The app does not extract or clean a legacy system. See the migration target contract for the exact boundary.

It accepts a versioned target package and:

• validates the declared schema and mapping digest;
• writes through the normal Frappe path;
• imports idempotently, with durable checkpoints and replay;
• quarantines faulty rows with a typed error code while sibling rows continue;
• records field provenance and returns an id_map of created or reused target records.

A batch contract error aborts the batch before normal row processing; a duplicate import returns an idempotent duplicate result. The import creates no automatic postings, payments, or approvals. Attachments and OCR are a separate integration slice. The contract needs no Helpifyr component.

Next step

Continue with Operations.