Domain Model — Insurance Concepts Primer
This section explains the health insurance concepts that underpin Olly's data model and maps each concept to the Go struct and microservice that owns it.
If You're New to Health Insurance
Core Financial Terms
Premium — The fixed amount an employer group or individual pays each billing period to maintain coverage. In Olly, premiums are modelled as PREMIUM charges on a LedgerEntry and collected via Invoice.
Deductible — The amount a member pays out-of-pocket before the plan begins paying for covered services. Tracked per PolicyTerm; the adjudication engine checks accumulator balances before applying plan benefits.
Copay — A flat fee a member pays at the point of care (e.g., £20 per GP visit). Stored in PolicyElement.CoverageTerms as a JSON benefit definition.
Coinsurance — The percentage of allowed charges a member pays after meeting their deductible (e.g., 20% member / 80% plan). Applied in the adjudication logic when computing ClaimLine.AmountPaid.
Out-of-pocket maximum — The annual ceiling on a member's total cost-sharing. Once reached, the plan pays 100% of covered services for the remainder of the term.
Policy Concepts
Policy vs. PolicyTerm vs. PolicyElement
| Concept | What it is | Go Struct |
|---|---|---|
| Policy | The master insurance contract | Policy |
| PolicyTerm | One coverage period (e.g., 1 Jan–31 Dec 2026) | PolicyTerm |
| PolicyElement | One insured unit within a term (employee or dependent row) | PolicyElement |
A Policy can have many PolicyTerm records over its lifetime (annual renewals). Each PolicyTerm has one or more PolicyElement rows — one per covered person. Elements carry a CoverageTerms JSON blob that encodes the specific benefit schedule (copays, coinsurance, limits) for that individual.
People Concepts
Member vs. Subscriber vs. Dependent
- Subscriber (Employee) — The primary insured person, typically an employee. Represented as a
PolicyElementwithElementType = "employee"linked to aPartyof typeINDIVIDUAL. - Dependent — A spouse, child, or other eligible family member covered under the subscriber's plan. Represented as a
PolicyElementwithElementType = "dependent". - Member — Umbrella term for any person covered under a
PolicyElement(subscriber or dependent).
An Account is the billing entity — it can be a company (BillingLevel = "ACCOUNT") for a group scheme, or an individual household.
Clinical / Administrative Concepts
Prior Authorization (Prior Auth) — A pre-approval requirement from the insurer before a member receives certain procedures or medications. Modelled as a PriorAuth entity. Claims for procedures that require prior auth are held until a linked PriorAuth with Status = "APPROVED" exists.
EOB (Explanation of Benefits) — A document sent to the member after a claim is adjudicated, summarising what the provider billed, what the plan allowed, what the plan paid, and what the member owes. Generated as a PDF by the Claims service and stored in S3. A corresponding FHIR ExplanationOfBenefit resource is written to the HAPI FHIR server.
Concept-to-Struct Mapping
| Insurance Concept | Go Struct | Service | DB Schema |
|---|---|---|---|
| Insurance account / billing entity | Account | policy-admin | policy_admin.accounts |
| Insurance contract | Policy | enrollment | enrollment.policies |
| Coverage period | PolicyTerm | enrollment | enrollment.policy_terms |
| Covered person / benefit schedule | PolicyElement | enrollment | enrollment.policy_elements |
| Policy change transaction | PolicyTransaction | enrollment | enrollment.policy_transactions |
| Quote / proposal | Quote | enrollment | enrollment.quotes |
| Underwriting decision | UnderwritingFlag | enrollment | enrollment.underwriting_flags |
| Medical claim | Claim | claims | claims.claims |
| Claim line item | ClaimLine | claims | claims.claim_lines |
| Prior authorization | PriorAuth | claims | claims.prior_auths |
| Premium invoice | Invoice | billing | billing.invoices |
| Payment record | Payment | billing | billing.payments |
| Ledger entry | LedgerEntry | billing | billing.ledger_entries |
| Installment plan | InstallmentSchedule | billing | billing.installment_schedules |
| Person or organisation | Party | policy-admin | policy_admin.parties |
| Role on a policy/account | PartyRole | policy-admin | policy_admin.party_roles |
| Healthcare provider | Provider | provider | provider.providers |
| Credentialing application | CredentialingRequest | provider | provider.credentialing_requests |
| Consent preference | ConsentRecord | consent | consent.consent_records |
| GDPR deletion request | DeletionRequest | consent | consent.deletion_requests |