Building a Claims & Financing Engine from the Ground Up

A hospital case can begin with an insured patient who needs help navigating a claim, or with a patient who needs a separate financing path. The customer experiences urgency and uncertainty; the system experiences documents, identity checks, status transitions, external organisations, money movement, deadlines, and human decisions.

• Claim-support journey: collect minimum intake data, establish authority, obtain policy and hospital documents, coordinate insurer queries, and track the claim to resolution.
• Financing journey: collect a separate application, perform authorised verification and assessment, record an accountable decision, establish repayment terms, and reconcile collections.
• Shared case operations: identity, consent or authority, documents, tasks, communication, audit history, deadlines, and role-based access.

Mobile intake and back-office portals are views over one case lifecycle. The domain model should remain stable when the frontend, vendor, or communication channel changes.

• Case identity: a non-recycled internal identifier; phone numbers and government identifiers are attributes, not durable primary keys.
• Participants and roles: patient, representative, hospital agent, operator, reviewer, insurer, lender, and payment provider.
• State and reason: every transition records who initiated it, the reason, evidence, policy version, and timestamp.
• Tasks and deadlines: required documents, insurer queries, reviews, follow-ups, payment events, and escalation dates.
• Documents by reference: encrypted object identity, document type, version, retention class, extraction state, and access policy.

A claim workflow crosses organisational boundaries that do not share one API or clock. The platform needs a durable timeline that can represent documents requested, queries raised, responses submitted, approvals, partial settlements, rejections, appeals, and closure without collapsing them into one mutable status string.

1. Validate the transition. Check the case type, current state, actor role, required evidence, and duplicate external reference.
2. Commit state and event intent together. The database transaction writes the case change and an outbox event.
3. Publish asynchronously. A dispatcher sends committed outbox records to the appropriate task or event channel.
4. Perform idempotent side effects. Notifications and vendor calls use stable operation identifiers and record their result.
5. Expose the timeline. Operators and customers see a filtered view of the same durable history.

Django signals can notify receivers when framework actions occur, but Django’s own signal guidance warns that signals can make code difficult to understand, adjust, and debug. Explicit application commands and domain events make core workflow dependencies easier to test.

A recurring repayment instruction is not a boolean called auto_pay. Registration, activation, scheduling, presentation, settlement, failure, retry, pause, cancellation, and reconciliation happen at different times and may be reported by different parties.

NPCI’s NACH overview describes NACH as infrastructure for high-volume, repetitive electronic transactions and mandate management. Actual participant roles, limits, notices, dispute processes, and regulatory obligations must be implemented from the applicable current rules and provider contract.

• Separate mandate and debit identity. One mandate can produce many scheduled collection attempts.
• Reconcile provider reports. API acceptance does not prove bank settlement; ingest authoritative status and settlement files or events.
• Make retries policy-driven. Respect attempt limits, dates, customer communication, and applicable rules.
• Preserve adjustments. Pauses, cancellations, changed schedules, refunds, and write-offs remain visible in the ledger and audit trail.

A notification should be caused by a committed business event, not by hoping a background task was published after a database save. The transactional-outbox pattern writes the event in the same transaction as the case change, then publishes it independently.

def transition_case(case_id, command, actor):
    with database.transaction():
        case = cases.lock(case_id)
        transition = policy.validate(case, command, actor)

        case.apply(transition)
        cases.save(case)

        outbox.append(
            event_id=stable_event_id(case.id, case.version),
            event_type="case.status_changed",
            aggregate_id=case.id,
            payload={
                "from": transition.previous_state,
                "to": transition.next_state,
                "reason_code": transition.reason_code,
            },
        )

    return case.snapshot()


def publish_outbox(record):
    broker.publish(
        topic=record.event_type,
        key=record.aggregate_id,
        payload=record.payload,
        idempotency_key=record.event_id,
    )
    outbox.mark_published(record.event_id)

Some partners provide structured webhooks or APIs; others still send automated email. Prefer authenticated structured integration when it exists. When polling a mailbox is unavoidable, treat email as an external protocol with identity, parsing, replay, and quarantine concerns.

• Keep the raw message. Store an immutable reference and cryptographic digest according to retention policy before parsing.
• Identify idempotently. Use mailbox identity, provider message ID, attachment digest, and external claim reference.
• Parse into a candidate event. Extract sender, claim identifier, status, reason, dates, and confidence without updating the case directly.
• Validate correlation. Confirm sender policy, case identity, allowed transition, and whether the message supersedes an earlier update.
• Quarantine ambiguity. Unknown templates, conflicting references, and low-confidence results go to an operator queue.

A policy document can contain dozens of pages of definitions, exclusions, schedules, limits, and endorsements. The goal of a KYP summary is not merely OCR. It is a traceable, human-reviewed transformation from source pages into a compact explanation.

The service formerly described as Form Recognizer is now documented as Azure Document Intelligence. It remains a dated example; service selection should be based on representative policies, field-level evaluation, data handling, regional availability, lifecycle, and cost.

A case may contain medical documents, identity records, policy details, credit information, bank mandates, contact history, and decisions with real consequences. Security and privacy requirements belong in the domain model and workflow—not only in infrastructure configuration.

• Minimise collection. Gather only the fields and documents required for the authorised case purpose.
• Separate roles. Hospital intake, claims operations, financing review, payment operations, support, and administration need different access.
• Encrypt and isolate. Protect data in transit and at rest, separate environments and tenants, and keep secrets outside application records.
• Audit reads and changes. Record evidence access, export, decision, override, document version, and policy version.
• Retain by data class. Source documents, extracted fields, communication, payment records, and derived summaries can require different schedules.
• Keep human accountability. Credit, coverage, medical, claim, and enforcement decisions remain owned by authorised people and organisations.

Asynchronous work protects the request path, but queue depth and retries can quietly turn into customer delay. Operational metrics must connect infrastructure state to case outcomes.

• Measure age, not only count. Track the oldest ready task, processing time, retry age, and time spent awaiting a person or partner.
• Make tasks idempotent. Celery’s task guidance notes that redelivery can occur and recommends idempotent task behavior.
• Bound retries. Retry only transient errors, with backoff, deadlines, and a terminal inspection path.
• Separate workloads. Long document jobs, quick notifications, mailbox ingestion, and reconciliation need independent capacity and timeouts.
• Reconcile external truth. Scheduled checks detect missing webhooks, incomplete outbox publication, unsettled debits, and stalled cases.
• Measure correction. Track document field corrections, status overrides, notification failures, disputed decisions, and reopened cases.

The original project reported producing a KYP document in under five minutes. Treat that as a historical outcome from one workload—not a current guarantee. Define service targets from document size, queue capacity, provider latency, review requirements, and measured percentiles.

The worker records extraction identity and confidence before creating a summary draft. Low-confidence or contradictory fields become review tasks rather than guessed values.

def process_policy_document(document_id: str, event_id: str) -> None:
    document = documents.claim(
        document_id=document_id,
        event_id=event_id,
        allowed_states={"queued", "retryable"},
    )
    if document is None:
        return

    source = secure_objects.open_verified(
        document.object_key,
        checksum=document.checksum,
    )
    extraction = document_ai.extract(
        source,
        schema_version=document.schema_version,
    )

    validated = validators.check(
        extraction.fields,
        source_pages=extraction.citations,
    )
    review_fields = [
        field for field in validated
        if field.confidence < field.review_threshold
        or field.has_conflict
    ]

    draft = summaries.create_from_validated_fields(
        fields=validated,
        require_source_citations=True,
    )

    documents.finish(
        document_id=document.id,
        extraction=validated.redacted(),
        summary_draft=draft,
        next_state="review_required",
        review_fields=review_fields,
    )

{
  "event_id": "evt_01J...",
  "event_type": "case.status_changed",
  "occurred_at": "2026-07-29T10:30:00Z",
  "aggregate": {
    "type": "claim_case",
    "id": "case_01J...",
    "version": 17
  },
  "transition": {
    "from": "insurer_query_received",
    "to": "response_under_review",
    "reason_code": "documents_uploaded"
  },
  "actor": {
    "type": "operator",
    "id": "user_01J..."
  }
}

1. Define states and owners. Every claim, application, mandate, debit, document, task, and review state has allowed transitions and an accountable actor.
2. Test transaction boundaries. Database commits, outbox publication, external calls, callbacks, and retries cannot create missing or duplicate effects.
3. Reconcile every provider. Detect missing notifications, inconsistent statuses, duplicate messages, and unsettled money movement.
4. Evaluate document fields. Use representative policies and field-level accuracy, confidence, citation, and reviewer-correction metrics.
5. Exercise access and retention. Test roles, revocation, document exports, audit trails, deletion schedules, and support access.
6. Keep people in the decision. Sensitive determinations have review evidence, override paths, explanations, and appeal or correction processes.