A Kafka topic carrying domain events between Olly services.
An MCP tool exposed by olly-mcp; consumed by AI agents.
A deployable Olly microservice (e.g. claims, billing).
An OpenSearch index used for full-text or analytics queries.
A Postgres table owned by an Olly service, holding domain data.
A Snowflake warehouse table for BI / actuarial reporting.
docs/site/domain/members.md § Account — The Billing Entity
docs/site/domain/billing.md § Premium Billing Cycle
docs/site/domain/index.md § Concept-to-Struct Mapping
The financial container that owns policies and receives invoices. An Account may bill at the ACCOUNT level (all policies consolidated, typical for employer groups) or at the POLICY level (each policy billed independently). All Charges, Invoices, Payments, and LedgerEntries roll up to the Account. Aligned to Socotra's Account resource, which also represents a billing entity holding policies and financial balances.
socotra/featureGuide/billing/installmentsAndInstallmentLattices.md (charges and billing concepts)
A named counter that tracks a member's year-to-date spending against a specific benefit limit — for example, the amount applied toward a deductible, out-of-pocket maximum, or visit cap. AccumulatorBuckets reset on the plan anniversary or calendar year boundary and are updated whenever a claim line is adjudicated. They feed eligibility checks during real-time prior-auth and claim decisions, ensuring that benefit caps are correctly enforced across all submitted claims within a coverage period.
docs/site/domain/billing.md § Ledger Entries (Double-Entry)
A manual debit or credit applied to an Account outside of the regular invoice cycle, such as a pro-rata refund on mid-term cancellation or a goodwill credit. Adjustments generate corresponding LedgerEntry records that maintain double-entry balance.
docs/site/domain/providers.md § Credentialing Lifecycle
A scheduled encounter between a Member and a healthcare Provider, booked through the care service. Appointments are linked to a care Episode and a specific ProviderSlot, and carry status (BOOKED, ATTENDED, CANCELLED) plus a telehealth link-out URL where applicable.
socotra/featureGuide/workManagement/diaries.md (audit trail and diary concepts)
An immutable log record capturing who did what to which entity and when, supporting regulatory compliance and internal governance. Audit items are created automatically whenever a sensitive consent, data-sharing, or policy action is performed, linking the acting user, the affected party, and the operation performed. They are append-only: no audit item can be modified or deleted, ensuring a tamper-evident trail for GDPR and clinical data governance purposes.
A short-lived API credential issued to a service or external integration to authenticate against the insurance platform API. AuthTokens are scoped to a tenant, carry an expiry timestamp, and are stored hashed. In Olly, API authentication is handled by Keycloak JWT tokens and OpenBao dynamic secrets; AuthToken as a platform-managed credential type is aspirational. Concept sourced from Socotra; not yet modeled in Olly code.
A per-policy flag indicating whether direct debit should be initiated automatically on the invoice due date. When Enabled is true, the billing service triggers payment collection without manual intervention, reducing late-payment risk.
Extensible key-value metadata that can be attached to any Socotra entity (policy, account, claim, etc.) without requiring a schema change. AuxData entries are schematised via AuxDataKeySet definitions that specify allowed keys, data types, and validation rules. In Olly, auxiliary data is currently stored as JSONB columns (e.g. Policy.Document, PolicyElement.Data); AuxData would provide a more structured, queryable alternative. Concept sourced from Socotra; not yet modeled in Olly code.
hand-curated v0 — alignments and lifecycle ported forward
A categorised allowance under a Coverage (e.g. "annual physiotherapy visits", "outpatient pharmacy"). Aspirational: not currently backed by an Olly service or Postgres table.
socotra/featureGuide/billing/invoicing.md (invoice aggregation at account level)
socotra/featureGuide/financials/accountingPrimer.md (account balance concepts)
An aggregated billing view that summarises the financial position of all active policies within a Group Scheme, giving employers and brokers a consolidated picture of outstanding invoices, total premiums due, and payment status across their entire member cohort. BillingAggregate is computed from the billing service's account and invoice data rather than stored as a persisted entity; it is assembled on-demand when the employer portal requests the scheme billing dashboard. The concept parallels account-level balance reporting in the Socotra platform, where invoice and payment totals roll up to the account.
docs/site/domain/billing.md § Invoice Lifecycle
A product-level billing configuration that governs invoicing frequency, payment due dates, grace period length, and retry strategy for a policy or account. BillingPlans abstract the billing rules away from individual policies, enabling consistent billing across all policies on a product. Concept sourced from Socotra; not yet modeled as a separate entity in Olly code.
Configuration for a broker integration, recording the broker's Party reference and their delegated authority limit — the maximum policy size the broker may bind without insurer countersignature.
An asynchronous batch job that processes a CSV or API upload of employee enrollments for a Group Scheme. Tracks total records, processed count, failure count, and per-row error messages to enable partial recovery and audit.
socotra/featureGuide/policyManagement/policyTransactions.md (transaction validation errors)
A structured error record produced when a single row within a BulkEnrollmentJob fails to process — for example, because a member's identifier is missing, coverage dates are invalid, or a product rule rejects the application. Each error captures the offending row reference, error code, and human-readable message so that HR administrators can correct and resubmit without re-processing the entire batch. Errors are aggregated on the parent BulkEnrollmentJob and surfaced in the employer portal's batch report view.
socotra/featureGuide/policyManagement/policyTransactions.md (batch policy issuance context)
A single member record submitted as part of a BulkEnrollmentJob, representing one employee or dependent whose coverage is being created or amended in a batch upload. BulkMember carries enough identity and coverage data (name, date of birth, product code, effective date) for the enrollment service to validate and bind a policy without a live quote flow. Successfully processed BulkMember records result in a fully active Member and MemberCoverage; failed rows generate BulkEnrollmentJobError entries.
A discrete monetary obligation raised against an Account, categorised as PREMIUM, TAX, or FEE. Charges are the atomic unit of billing: each InvoiceLineItem references exactly one Charge, and each Charge generates a corresponding DEBIT LedgerEntry. Aligned to Socotra's Charge resource, which similarly represents a fee or premium amount applied to a policy account.
docs/site/domain/claims.md § Claim State Machine
A member's request for reimbursement of covered medical services. Claims are submitted complete and progress through adjudication (SUBMITTED → UNDER_REVIEW → APPROVED/REJECTED → PAID → CLOSED). Each Claim is itemised into ClaimLine records and may carry supporting ClaimDocument attachments. Aligned to Socotra's Claim resource, which also represents an insurance loss event progressing through an adjudication lifecycle.
socotra/featureGuide/claims/fnol.md (claim lifecycle and data model)
A denormalised read model that aggregates a Claim together with its ClaimLines, adjudication outcome, prior-auth reference, and payment amounts into a single response payload for the member portal. ClaimDetail avoids multiple round-trips when displaying a claim receipt or EOB to a member. It is not a separately persisted entity; the claims service assembles it on the fly from the underlying relational tables and exposes it through the member-portal-api contract.
docs/site/domain/claims.md § What Happens at Each Transition
A supporting file attached to a Claim during adjudication, such as a medical invoice, discharge summary, or diagnostic report. ClaimDocument records store the S3 URL, content type, and upload timestamp; they are created when a claim enters PENDING_INFO status.
docs/site/domain/claims.md § Appeal Process
An immutable audit record of every status change, actor action, and note on a Claim. ClaimEvents are append-only and include APPEAL_SUBMITTED and APPEAL_DENIED events alongside normal state transitions, forming a complete adjudication audit trail.
docs/site/domain/claims.md § ClaimLine Explained
One itemised procedure or service within a Claim, corresponding to a loop in an EDI 837 transaction. Records the billed amount (AmountClaimed), the plan-allowed amount (AmountAllowed), and the plan's payment (AmountPaid), with ANSI X12 reason codes for any contractual adjustment.
socotra/featureGuide/claims/fnol.md (first notice of loss and claim creation)
The intake payload a member or provider submits to initiate the claims adjudication process. A ClaimSubmission bundles the member identifier, incident date, diagnosis codes, procedure codes, provider reference, and any supporting document references into a single request. On successful ingestion the claims service creates a Claim entity and transitions it to the SUBMITTED state, from which adjudication, prior-auth checks, and payment flow proceed.
socotra/featureGuide/claims/fnol.md (claim data model overview)
A lightweight projection of a Claim designed for list views in the member portal and broker dashboard, returning only the fields needed for scanning — claim reference, date of service, provider name, status, and total amount — without the full line-item detail. ClaimSummary is generated by the claims service at query time and is not persisted independently; it complements ClaimDetail by giving consumers a fast, paginated overview before they drill into individual claims.
A fee payable to a broker when a policy they introduced is bound or renewed. Commission records capture the applicable rate, computed amount, and settlement status, and are reconciled against invoices generated by the billing service.
A clinically established diagnosis attached to a Member, sourced from Encounter outputs or self-reported history. Aspirational: not currently backed by an Olly service or Postgres table.
socotra/featureGuide/policyManagement/policyManagementTopicIndex.md (tenant configuration concepts)
A versioned, tenant-scoped package of product and billing configuration that is deployed atomically to the policy-admin service. A ConfigBundle bundles product definitions, rule sets, market profiles, document templates, and installment plan settings into a single artifact, ensuring that all configuration is consistent and auditable. Deploying a new ConfigBundle version advances the active product configuration without requiring individual resource updates, supporting zero-downtime configuration releases.
socotra/featureGuide/workManagement/userAssociations.md (user data governance context)
A single discrete consent decision within a ConsentRecord, capturing the consent type (e.g. NHS_DATA_SHARING, MARKETING_EMAIL, THIRD_PARTY_ACCESS), the decision value (granted or withdrawn), and the timestamp at which the decision was recorded. ConsentItems provide the granular audit trail required under GDPR Article 7 and NHS data governance standards, allowing each consent category to be independently granted or withdrawn without affecting the member's other consent preferences.
docs/site/domain/members.md § Consent Types and Why They Matter
A member's preference for a specific consent type (e.g. NHS_DATA_SHARING, WEARABLE_SYNC, MARKETING_COMMUNICATIONS), keyed by (PartyLocator, ConsentType). At most one record per combination exists; the Granted boolean captures the current preference.
A named contact point associated with an Account or Policy — distinct from the Account holder Party. Contacts carry a name, role (e.g. BILLING_CONTACT, BENEFITS_ADMINISTRATOR), email, and phone, enabling multiple communication targets per account. In Olly, contact information is currently embedded in the Party record; Contact as a separate entity is aspirational. Concept sourced from Socotra; not yet modeled in Olly code.
An AI chat session between a user and the Olly AI assistant, scoped to an organisation (org_locator). Conversations contain an ordered sequence of Messages and carry a persona identifier that controls the assistant's behaviour.
docs/site/domain/policies.md § PolicyElement
The abstract insurance entitlement a Member holds under a Policy at a given point in time. Coverage is the eligibility service's read model: it denormalises PolicyElement and MemberCoverage data into a queryable form for fast eligibility checks during claim adjudication.
docs/architecture/overview.md § Data Flow
A running balance tracking how much of a benefit limit a Member has consumed in a PolicyTerm — deductible, out-of-pocket maximum, or benefit-category cap. Accumulators are loaded and updated during adjudication to determine how much the plan pays on each ClaimLine.
docs/site/domain/policies.md § PolicyTerm and PolicyElement
A discrete benefit category within a product definition, specifying the type of coverage (e.g. INPATIENT_HOSPITAL, OUTPATIENT_SPECIALIST, MENTAL_HEALTH) and its associated benefit parameters such as copay, coinsurance percentage, deductible, and annual limit. In Olly, CoverageTerms are currently embedded as a JSONB blob on PolicyElement; Socotra models them as a first-class configurable resource. Concept sourced from Socotra; not yet modeled as a separate entity in Olly code.
A provider's application to join the Olly network, implemented as a Temporal workflow to handle the multi-week human review process. Records submission timestamp, reviewer decision (APPROVED/REJECTED), and reviewer notes; on approval, Provider.NetworkStatus is set to ACTIVE.
socotra/featureGuide/policyManagement/policyStatus.md (status lifecycle patterns)
A read-model snapshot of where a CredentialingRequest currently stands in the provider verification lifecycle. CredentialingStatus exposes the stage (e.g. DOCUMENTS_RECEIVED, VERIFICATION_IN_PROGRESS, APPROVED, SUSPENDED), the date the last status change occurred, and any blocking reason notes. Brokers and network managers query it to track which providers are cleared for service without reading the full credentialing workflow history; it is updated whenever the underlying CredentialingRequest transitions state.
An unapplied balance on an Account that can be applied against future invoices — arising from overpayments, mid-term cancellation refunds, or goodwill adjustments. Credits are distributed (CreditDistribution) to specific invoices to reduce the amount due. In Olly, credits are currently handled as CREDIT-direction LedgerEntries and Adjustment records; Socotra models them as a distinct distributable entity. Concept sourced from Socotra; not yet a separate entity in Olly code.
socotra/featureGuide/policyManagement/coverageTerms.md (deductible and limit coverage term types)
A real-time snapshot of a member's progress toward satisfying the deductible threshold on their active coverage for the current benefit period. DeductibleStatus combines the configured deductible limit from the coverage terms with the year-to-date amounts applied from adjudicated claims, exposing the remaining balance a member must pay before the insurer begins covering costs. It is computed by the eligibility service from AccumulatorBucket values and coverage term data, and is surfaced during eligibility checks and in the member portal.
docs/site/domain/members.md § GDPR Deletion Workflow
A GDPR Article 17 right-to-erasure request for a Party. SOFT deletion anonymises PHI fields while preserving referential integrity; HARD deletion purges all party data with tombstones. A Temporal workflow fans out the request to every service holding PHI for that PartyLocator.
docs/site/domain/billing.md § Grace Period and Delinquency Handling
A formal delinquency record created when an Invoice remains unpaid past its grace period. Delinquency tracks the escalation timeline from missed payment through lapse notification to cancellation, and may be subject to a moratorium (suspension of delinquency processing). In Olly, delinquency state is currently embedded in Invoice and Policy fields; Socotra models it as a standalone lifecycle entity. Concept sourced from Socotra; not yet a separate entity in Olly code.
A care-pathway instruction for a Member to undergo diagnostic tests (imaging, blood work, etc.), generated within a clinical Episode. Records the referring provider, target clinic, referral type, and the resulting Appointment locator once booked.
A time-stamped note or task record attached to an insurance entity (policy, claim, account), used by operations teams to track action items, follow-ups, and adjudicator notes. DiaryEntries differ from audit events in that they are authored by humans for human consumption and can be updated. Concept sourced from Socotra; in Olly, notes are currently embedded in claim and credentialing event records.
An outbound payment from the insurer to a payee — such as a claims payment to a provider or a refund to a policyholder. Disbursements are distinct from Payments (inbound premium receipts) and are tracked separately for cash management and regulatory reporting. Concept sourced from Socotra; in Olly, provider claim payments are currently modelled as outbound Payment records rather than a distinct Disbursement entity.
docs/site/domain/claims.md § EDI 837 / 835 Context
A generated or uploaded file associated with a policy, claim, or member record. Documents include policy schedules, Explanations of Benefit (EOBs), EDI-generated PDFs, and consent forms. Files are stored in S3 with SSE-KMS encryption and referenced by URL. Aligned to Socotra's Document resource, which similarly represents persisted document instances attached to insurance entities.
socotra/featureGuide/documents/documentManagement.md (document retrieval and association)
A lightweight projection of a Document containing only the metadata fields needed for list and browse views — document reference, type, associated entity (policy or claim), creation date, and download URL — without the full binary payload. DocumentSummary allows the member portal to display a document inbox and let members choose which files to download, deferring retrieval of the actual content until explicitly requested. It mirrors the document management pattern described in the Socotra platform, where documents are associated with policies, transactions, quotes, and claims and retrieved by reference.
socotra/featureGuide/policyManagement/policyStatus.md (coverage and policy status)
A consolidated snapshot of eligibility status for every active member in a Group Scheme, used by HR administrators and brokers to verify that all employees have valid, in-force coverage. The EligibilityRoster aggregates MemberCoverage records across the scheme's policies and returns a structured list showing each member's coverage tier, effective date, and eligibility status. It is assembled on demand from eligibility service data rather than persisted independently, and serves as the primary audit artefact for group scheme compliance checks.
A clinical interaction between a Member and a Provider — appointment, hospital admission, telehealth call, etc. Aspirational: not currently backed by an Olly service or Postgres table.
socotra/featureGuide/policyQuotation/quotes.md (quote issuance creating the policy)
The act and record of a member being admitted into a coverage product, tying a Party to a Policy with a defined effective date and coverage tier. An Enrollment is initiated either through the quote-and-bind flow (for individual members) or via a BulkEnrollmentJob (for group schemes). Once complete, it results in an active MemberCoverage record that gates eligibility checks and claim adjudication. The enrollment service orchestrates the transition from a bound quote to an in-force policy, including triggering billing setup and notification dispatch.
socotra/featureGuide/documents/documentManagement.md (document association with financial entities)
socotra/featureGuide/billing/invoicing.md (invoice document rendering)
A pointer to an Explanation of Benefits document generated after a claim is adjudicated, linking the claim to the rendered EOB file that details what was billed, what the insurer allowed, what was applied to the deductible, and what the member owes. EOBReference stores the document locator and metadata so the billing and member-portal services can surface the EOB alongside the invoice without re-fetching the full claim payload. It is analogous to the document reference pattern used throughout the Socotra platform where documents are associated with financial transactions.
A bounded care episode — a single clinical interaction or course of treatment — linking a triage Session to one or more Appointments, Prescriptions, and DiagnosticsReferrals. Episodes carry a care type (GP, SPECIALIST, MENTAL_HEALTH) and close when the clinical need is resolved.
A product-level metadata schema entry that defines a custom field (name, type, required flag, allowed values) collectible on policies, quotes, or transactions of a given ProductVersion. Field definitions drive dynamic form rendering in the employer and member portals.
docs/site/domain/billing.md § Payment Methods
A stored payment method on file for an Account — such as a bank account (for direct debit), credit card token (for card payments), or ACH routing details. FinancialInstruments are used by the autopay and billing services to initiate payment collection without requiring the account holder to re-enter payment details. Concept sourced from Socotra; Olly stores payment method details in payment gateway tokens but has no explicit FinancialInstrument entity yet.
First Notice of Loss — the initial report filed by a policyholder or claimant to notify the insurer of an insured event before a full claim is submitted. An FNOL captures the date, nature, and location of the loss and creates a claim shell that the adjudication team can enrich. In Olly's current model, claims are submitted complete; FNOL as a pre-claim stage is not yet implemented. Concept sourced from Socotra; not yet modeled in Olly code.
docs/site/domain/billing.md § Installment Schedules
A configuration template that defines the frequency, number of installments, and billing rules for splitting a premium into periodic payments. InstallmentPlans are assigned to products or accounts and drive the generation of InstallmentSchedule instances. Concept sourced from Socotra; not yet modeled as a separate entity in Olly code (currently embedded in InstallmentSchedule).
A plan for splitting an annual premium into periodic invoices. The billing scheduler reads active InstallmentSchedules and generates the next Invoice on each due date until all installments are exhausted, supporting MONTHLY, QUARTERLY, and ANNUAL frequencies.
A demand for premium payment issued to an Account for one billing period. Invoices progress through DRAFT → FINALISED → PAID (or VOID). Each Invoice contains one or more InvoiceLineItem rows and carries grace period and delinquency timestamps used to trigger policy lapse. Aligned to Socotra's Invoice resource, which also models a billing statement with lifecycle states and settlement tracking.
One line on an Invoice, linking to a specific Charge record (PREMIUM, TAX, or FEE) and its amount. The sum of all InvoiceLineItem amounts equals Invoice.TotalAmount; this denormalisation enables efficient invoice rendering without re-summing charges.
An automated quality-scoring evaluation of a triage Session by a judge LLM, scoring tone, PRD compliance, and safety against a rubric. Judgements are produced by the triage evaluation harness and stored to track model regression across prompt versions.
A named chart-of-accounts entry in the double-entry bookkeeping system, representing a category such as PREMIUM_RECEIVABLE, TAX_PAYABLE, or CLAIMS_EXPENSE. LedgerAccounts provide the account classification dimension for regulatory financial reporting and actuarial analysis. In Olly, LedgerEntry records carry direction and type but are not yet categorised against a formal chart of accounts. Concept sourced from Socotra; not yet modeled in Olly code.
A double-entry bookkeeping record for every financial movement on an Account. EntryType values are CHARGE, PAYMENT, ADJUSTMENT_DEBIT, ADJUSTMENT_CREDIT, and REVERSAL; Direction is DEBIT or CREDIT. The net sum of all LedgerEntries for an Account equals its current balance.
A versioned regulatory and billing configuration bundle for a specific jurisdiction or market segment. MarketProfiles govern which product features are available, which regulatory regime applies, and which document templates are used — enabling multi-market operation from a single platform.
A published snapshot of a MarketProfile at a point in time, capturing jurisdiction code, regulatory regime, feature flags, billing rules, mandatory fields, and document template assignments. Policies reference the MarketProfileVersion in force at their inception date.
A reference to a drug or therapeutic agent within Olly's clinical data model, used primarily in the context of Prescriptions issued during a care Episode. Medication records carry the drug name, formulary classification, and any relevant prior-auth requirements, enabling the platform to check whether a prescribed drug is covered under a member's benefit plan before dispensing. The concept is clinical in origin and has no direct Socotra analogue; it exists in Olly to support the triage and care pathway services.
docs/site/domain/members.md § The Party Model
docs/site/domain/index.md § People Concepts
An individual insured person (primary subscriber or dependent) covered under a PolicyElement. A Member's identity is stored as a Party of type INDIVIDUAL; their coverage entitlements are in MemberCoverage. The term "member" is the business-facing umbrella for any covered person.
The eligibility service's denormalised read model of a Member's active coverage on a Policy and PolicyTerm. Populated by consuming enrollment.completed events, it enables fast eligibility lookups during claim adjudication without joining across enrollment tables.
A single turn in an AI chat Conversation — either a user message or an assistant response. Messages store the LLM role (user/assistant/tool), content, tool call metadata, and token usage for cost tracking and prompt tracing via Langfuse.
A temporary suspension of billing enforcement actions (delinquency escalation, lapse, cancellation) for a defined set of policies — typically applied during regulatory-mandated relief periods or catastrophe events. Moratoriums carry match criteria to identify affected policies and a rule set governing which billing events are suppressed. Concept sourced from Socotra; not yet modeled in Olly code.
A delivery record for a single outbound notification (push, SMS, or email) sent on behalf of a domain event. Captures the channel, status (SENT/FAILED), subject, body preview, attempt count, and failure reason to support retry logic and delivery auditing.
A Member's channel and opt-out preferences for notifications. Records preferred delivery channel (PUSH, SMS, EMAIL), contact details, and the list of event types the member has explicitly opted out of receiving.
The aggregate container of all NotificationPreference records for a given Member, representing their complete channel and opt-in/opt-out configuration across event types. The notifications service reads this container when deciding how to route an outbound notification — email, SMS, push, or in-app — checking each preference before dispatching. NotificationPreferences is returned as a single structured object by the GET preferences endpoint so that the member portal can render the full preferences screen in one call without assembling individual records client-side.
The unified identity record for any person or organisation on the platform — members, employers, brokers, and providers all share this entity, distinguished by Type (INDIVIDUAL, ORGANISATION, PROVIDER). PHI fields are application-layer encrypted before storage; the Locator is the externally shareable stable reference.
docs/site/domain/members.md § PartyRole — Roles on Policies and Accounts
A contextual role a Party plays on a specific entity (Account, Policy, or Quote). One Party can hold multiple roles across multiple entities — for example, ACCOUNT_HOLDER on an employer account and INSURED on individual policies.
A guided clinical decision flow (NHS 111 style) that maps a presenting Symptom set to a recommended care destination. Aspirational: not currently backed by an Olly service or Postgres table.
A record of funds received against an Invoice. Payments are collected via DIRECT_DEBIT, CARD, or BANK_TRANSFER. When a Payment reaches SETTLED status and the aggregate payments equal the Invoice total, the Invoice transitions to PAID and a CREDIT LedgerEntry is posted. Aligned to Socotra's Payment resource, which also represents a financial settlement event linked to a billing account.
docs/site/domain/policies.md § Policy Lifecycle
docs/site/domain/policies.md § PolicyStatus State Machine
The master insurance contract between an insurer and an Account. A Policy is created when a Quote is accepted and the first premium collected. It accumulates PolicyTerm records on annual renewal and tracks status through ACTIVE, LAPSED, CANCELLED, and EXPIRED states. Aligned to Socotra's Policy resource, which also represents a central insurance contract entity with term and transaction sub-records.
docs/site/domain/members.md § Employee vs. Dependent
One insured unit within a PolicyTerm — either an employee (primary subscriber) or a dependent. PolicyElement carries the per-member benefit schedule (copay, coinsurance, deductibles, OOP max) as a CoverageTerms JSON blob, and a stable StaticID used to track accumulators across term versions.
A value for a custom FieldDefinition on a specific Policy, supporting the product's dynamic data model. PolicyFieldValues allow product teams to add configurable data fields to policies without database schema migrations.
One bounded coverage period on a Policy, typically annual. PolicyTerms carry a sequential TermNumber, inclusive EffectiveFrom/EffectiveTo dates, and a status that mirrors the parent Policy. Accumulators, ClaimLines, and MemberCoverage records are all scoped to a specific PolicyTerm.
docs/site/domain/policies.md § Enrollment, Renewal, Endorsement, and Cancellation
An immutable record of every post-issuance change to a Policy, including ISSUANCE, RENEWAL, ENDORSEMENT, CANCELLATION, REINSTATEMENT, and REVERSAL. Each transaction carries an EffectiveDate that may differ from the processing date, and optionally references a PolicyTerm. Aligned to Socotra's PolicyTransaction resource, which similarly records structured change events against a policy.
The amount payable by the Member (or scheme) for a Policy, on a configurable cadence. Aspirational: not currently backed by an Olly service or Postgres table.
A medication prescription issued by a healthcare Provider within a care Episode, recording the medication name, prescribing provider, and issue timestamp. Prescriptions may be linked to prior auth requirements for formulary-controlled drugs.
docs/site/domain/claims.md § Prior Authorization Flow
A pre-approval from the insurer required before certain procedures are performed. PriorAuth progresses from PENDING through APPROVED or DENIED. Claims for procedures requiring prior auth that lack an APPROVED record are automatically rejected with ANSI reason code CO-15.
An insurance plan definition (e.g. "Olly Select PMI") owned by policy-admin. A Product groups one or more versioned benefit schedules (ProductVersion). It carries a Line of Business (lob) classifier and a status lifecycle from DRAFT through ACTIVE to RETIRED. Aligned to Socotra's Product configuration entity, which also defines the schema and rules governing policies written under it.
A published, immutable version of an insurance Product containing the policy schema, claim schema, element schema, charge types, and status lifecycle. Quotes and Policies reference a specific ProductVersion to ensure benefit schedules remain stable after changes to the parent Product.
docs/site/domain/providers.md § Provider Entity
A credentialed healthcare organisation or individual practitioner in the Olly network. Identified by NPI (National Provider Identifier) for use in EDI 837 transactions and prior auth requests. NetworkStatus (PENDING/ACTIVE/INACTIVE) determines in-network claim adjudication rates and member cost-sharing obligations.
A specific bookable time window at a Provider, with start/end times and a status (AVAILABLE/BOOKED/CANCELLED). When a Member books an Appointment, the linked ProviderSlot transitions to BOOKED; cancellations restore it to AVAILABLE.
docs/site/domain/policies.md § Quote → Policy Issuance Flow
A priced proposal that precedes a Policy. Quotes advance through DRAFT → PRICED → UNDERWRITTEN → ACCEPTED/DECLINED → (if accepted) converted to a Policy. A Quote holds the rated premium, benefit schedule, and applicant data as a JSONB Document blob, and expires after a configurable timestamp. Aligned to Socotra's Quote resource, which also models a priced insurance proposal that can be accepted or declined.
An immutable audit record of every status change on a Quote — from DRAFT through pricing, underwriting, acceptance or decline, and expiry. QuoteEvents capture the event type and payload at each transition, forming the complete quote history.
A value for a custom FieldDefinition collected on a Quote during the application process. Analogous to PolicyFieldValue but scoped to the pre-issuance quote, supporting the same product-defined dynamic data model.
The structured clinical disposition produced by the triage engine at the end of a member's triage Session, advising the appropriate care pathway — for example, self-care, GP consultation, urgent care, or emergency services. A Recommendation bundles the suggested action, the urgency level, and a plain-language rationale derived from the member's reported symptoms and clinical reasoning. It is the terminal output of a completed triage conversation and may trigger a DiagnosticsReferral or Appointment booking depending on the pathway selected.
docs/architecture/overview.md § Security Boundaries
A named permission bundle that can be assigned to platform users, controlling which resources and operations they can access. Roles are evaluated by the OPA policy engine at APISIX and within each service. In Olly, roles are managed in Keycloak as realm roles; a platform-native Role entity would enable programmatic role management without Keycloak API calls. Concept sourced from Socotra; not yet modeled as a standalone entity in Olly code.
A single executable policy rule within a RuleSet, with a condition expression, an effect (e.g. REJECT, SURCHARGE, FLAG), a human-readable message, and a priority. Rules are evaluated by the underwriting and adjudication engines against quote or claim data.
An audit record of a single Rule being evaluated against a specific entity (Quote, Claim, or Policy). Captures whether the condition matched, which effect was applied, and the timestamp, providing a traceable decision log for regulatory audit.
socotra/featureGuide/underwriting.md (underwriting plugin and flag evaluation)
The structured context object passed into a RuleSet evaluation, containing the data required for the underwriting or adjudication engine to assess each Rule's condition. RuleInput bundles the entity under evaluation (quote, claim, or policy), the triggering event, and any auxiliary data fields (demographic, clinical, or financial) that rules may reference. It is constructed at evaluation time from the current state of the entity and discarded after evaluation, with the results persisted as RuleEvaluation audit records.
A named collection of Rules associated with a ProductVersion and a trigger context (e.g. QUOTE_UNDERWRITING, CLAIM_ADJUDICATION). RuleSets are the unit of rule configuration: adding or retiring rules is done by publishing a new RuleSet version.
socotra/featureGuide/underwriting.md (underwriting configuration and rule sets)
A versioned collection of RuleSets packaged together for deployment as a coherent configuration update. A RuleSetBundle groups all the rule sets that belong to a single ProductVersion and trigger context (underwriting, adjudication, billing) so they can be validated, tested, and published atomically. Publishing a new bundle replaces the prior active rule configuration for the product version without requiring individual rule set updates, mirroring the tenant configuration deployment model described in the Socotra platform where all rule and configuration artefacts are deployed together.
docs/site/domain/members.md § Employer Group Scheme → Member Relationship
An employer group insurance arrangement linking an employer Party to a cohort of member policies. Schemes are administered by the group-scheme service, carry a locator code used in bulk enrollment uploads, and scope the employer portal to the correct member population.
The association between a Group Scheme and an individual member's policy. SchemeMember records the member's Party locator, policy locator, and enrollment status, enabling the employer portal to list and manage all covered employees within the scheme.
A named sub-division of a policy's insured population or coverage period used for targeted billing and reporting — for example, separating employee-only from family coverage tiers, or dividing a multi-location employer account by cost centre. Segments drive differential premium calculation and claims allocation. Concept sourced from Socotra; not yet modeled in Olly code.
A single AI triage interaction in which a user works through a clinical decision tree (pathway) to receive a disposition. Sessions carry chief complaint, demographic parameters (sex, age), current pathway state, and a final disposition (e.g. SEE_GP, GO_TO_ED, SELF_CARE).
A presenting complaint reported by a Member during triage, mapped to SNOMED-CT clinical findings where licensed. Aspirational: not currently backed by an Olly service or Postgres table.
A reusable HTML/text layout used by the document service to generate member-facing communications — policy schedules, welcome letters, Explanation of Benefits PDFs, and renewal notices. Templates are keyed by market code and template type. Aligned to Socotra's Template resource, which also defines document generation templates used for policy documents and correspondence.
In Socotra's model, a Term represents a versioned coverage period on a policy, analogous to Olly's PolicyTerm. The Term entity in Socotra carries the full effective date range, premium amount for that period, and a list of insured elements. Olly's PolicyTerm and PolicyElement together cover this concept. Concept sourced from Socotra; Olly models this as PolicyTerm + PolicyElement.
A value for a custom FieldDefinition collected on a PolicyTransaction (e.g. an endorsement or renewal), capturing transaction-specific dynamic data defined by the product schema.
A single conversational exchange within a triage Session — one user input plus the agent's response. Turns record the pathway state before and after the exchange, any tool calls made by the agent, and tool results, enabling full replay of the triage interaction.
An individual underwriter decision (APPROVE, BLOCK, or DECLINE) applied to a Quote. Multiple flags can coexist on a single Quote; the strictest decision wins. Flags record the reason for the decision and can be voided if superseded. Aligned to Socotra's UnderwritingFlag resource, which similarly captures underwriting decisions during the quote review process.
docs/architecture/overview.md § Technology Choices
An authenticated platform user — in the triage service context, a triage agent identified by username and hashed API key, with demographic attributes (sex, age) used for clinical pathway routing. Platform-wide human identity is managed in Keycloak. Aligned to Socotra's User resource, which also represents an authenticated operator with access credentials.
An outbound HTTP callback registration that delivers domain events (e.g. policy.issued, claims.adjudicated) to external systems in real time. Webhooks carry an endpoint URL, subscribed event types, authentication headers, and retry strategy. Concept sourced from Socotra; Olly currently delivers events via Kafka topics rather than HTTP webhooks.
A named team of operations staff (claims adjusters, underwriters, credentialing reviewers) to whom work items can be assigned. Workgroups enable round-robin or skill-based routing of claims, prior auth requests, and credentialing reviews. Concept sourced from Socotra; Olly currently assigns reviewers directly; a Workgroup abstraction is aspirational.
The formal accounting recognition that an outstanding receivable (unpaid invoice or charge) will not be collected, resulting in a credit entry to the PREMIUM_RECEIVABLE ledger account. Write-offs are typically applied after a policy has been cancelled following the lapse window. Concept sourced from Socotra; not yet modeled as a separate entity in Olly code.
An APISIX gateway route mapping a public path to a service.
A Keycloak client (web-employer, web-member, etc.) used for auth.