Chartwell/Books/Accounting/Policy.txt

Policy Module – RAG Knowledge Base

Chunk 1: Module Overview
Metadata: module=Policy, type=overview, location=CMH.HFA.Accounting.Orchestration/src/Policy, domain=policyAccounting, scope=fullLifecycle
Purpose: Comprehensive Lambda functions and services for insurance policy lifecycle events and accounting transactions
Functional Domains: Policy issuance/renewals, monetary/non-monetary endorsements, policy cancellations, refunds, commissions, invoice adjustments, licensing management
Integration Points: Oracle Fusion AR (invoice/credit memo posting), Oracle OIC (memo line lookups), customer management, commission tracking, AWS Step Functions
Key Concepts: invoice generation, credit memo creation, commission allocation, endorsement adjustments, refund distribution, transaction line building, temporal validity, memo line configuration

Chunk 2: MapOracleInvoice Service
Metadata: component=MapOracleInvoice, type=Lambda, operations=2, pattern=autoMapper, purpose=invoiceCreation
Description: Orchestrates transformation of policy events into Oracle AR invoice structures
Operations:

Map: Processes PolicyIssuedEvent for new invoices
MapRenewed: Processes PolicyRenewedEvent for renewal invoices
Processing Flow: Receives policy event + customer data, applies AutoMapper, determines transaction type (internal/external), invokes commission service, builds transaction lines using memo line lookups
Transaction Type Logic: Maps Internal vs External based on BillingType, ProductType, lender status

Chunk 3: Invoice Commission Processing
Metadata: component=InvoiceCommission, interface=IInvoiceCommission, pattern=multiStage, purpose=commissionCalculation
Description: Multi-stage pipeline to calculate commission-related transaction lines
Stages:

Pre-invoice line creation → maps premium and sales tax
Commission line generation → Retail vs HFA
Memo line retrieval → GL accounts via Oracle OIC
Transaction line finalization → GL accounts, amounts, commission metadata
Sorting → by type (premium, commission, fees) via TransactionLineComparer
Licensing Integration: Differentiates licensed/unlicensed home centers for commission routing

Chunk 4: Policy Cancellation Processing
Metadata: component=PolicyCancelService, operation=MapEventPayload, output=CreditMemo, purpose=cancellationAccounting
Description: Generates credit memos for policy cancellations with coverage-based refund calculations
Input: InsurancePolicyCancelledEventPayload (coverage blocks, unearned premium, sales tax refund, cancellation reason, billing type, other interests)
Credit Memo Generation: Negates original invoice amounts, maps cancellation reason to Oracle credit reason codes, determines internal/external transaction type, links to original invoice
Cancellation Reason Mapping: CustomerRequest, Flat, NonPayment, Repossession, ReplacementPolicy, Underwriting, HomeSold → "HFA-{Reason}" codes
Coverage Block Processing: Allocates premiums to corresponding GL accounts for accurate refunds

Chunk 5: Refund Adjustment Service
Metadata: component=RefundAdjustmentService, operation=GetCancellationRefundAdjustment, output=Adjustment, recipients=3
Description: Creates AR adjustment records for cancellation refunds
Recipient Types:

Retail → "HFA Retail I/C Refund"
VMF → "HFA VMF I/C Refund"
Customer → "HFA Auto Customer Refund"
Adjustment Configuration: Sets ReceivableTrxId, OrgId, SetOfBooksId
Comment Generation: Auto-generates descriptive comments
Validation: Throws exception if refund amount zero or credit memo missing

Chunk 6: Endorsement Adjustment Service
Metadata: component=EndorsementAdjustmentService, operation=MapEndorsementAdjustments, distribution=installmentBased, purpose=balanceSpread
Description: Allocates endorsement balance changes across invoice installments proportionally
Distribution Logic:

Single installment → full amount, rounding applied
Multiple installments → divided equally, final rounding adjustment
Zero balance → empty adjustment list
Adjustment Structure: Adjustment records with CustomerTrxId, PaymentScheduleId, ReceivablesTrxId, AdjustmentType="M", Amount, ApplyDate, CurrencyCode, OrgId, SetOfBooksId
Use Case: Monetary endorsements requiring proper AR aging

Chunk 7: Non-Monetary Endorsement Processing
Metadata: component=ProcessNonMonetaryEndorsementCustomerLambda, type=Lambda, purpose=customerUpdates, changes=demographic
Description: Updates customer data without affecting premium/fees
Supported Updates:

Name: first, middle, last, suffix
Address: street1-3, city, stateCode, zip.base/ext, country
Processing Pattern: Iterates NonMonetaryUpdate objects, applies property path to Oracle customer, targets MAILING site
Output: Modified OracleCustomer for downstream synchronization

Chunk 8: Invoice Filtering and Selection
Metadata: components=2, purpose=invoiceQuery, operations=filterAndSelect

FilterOpenInvoicesLambda: Filters invoices with balance >0, orders by TransactionDate descending
SelectValidInvoiceLambda: Selects most recent invoice matching valid transaction type whitelist (HFA internal/external, plan/type change, conversion), open balance >0
Valid Transaction Types: HfaInvoiceInternal, HfaInvoiceExternal, HfaInvPlanChgInt/Ext, HfaInvTypeChgInt/Ext, HfaInternConv, HfaExternConv
Use Cases: Endorsement workflows, billing change workflows

Chunk 9: Policy Number Management
Metadata: component=DecrementPolicyNumberLambda, type=Lambda, operation=numberManipulation, pattern=wrapping
Description: Decrements numeric suffix of policy numbers with wraparound logic
Algorithm: Last 2 characters numeric → decrement modulo 100, maintains prefix, zero-padded 2-digit suffix
Validation: Policy number min 2 chars, last 2 chars parse as int
Example: "POL-12345-03" → "POL-12345-02"; "POL-12345-00" → "POL-12345-99"
Use Case: Policy versioning/renewal numbering

Chunk 10: Policy Licensing Management
Metadata: component=PolicyLicensingLambda, operations=2, purpose=licensingInfo, determination=dealerBased
Operations:

MapIssuedLicensingInfo: Extracts licensing from issuance event
MapRenewedLicensingInfo: Extracts licensing from renewal event + previous invoice
LicenseInfo: IsHomeCenterLicensed, MasterDealerNumber, HomeCenterId, StateCode
Dealer Logic: Producer=ClaytonRetail AND Product≠ESC → MasterDealerNumber=29; else 0
Purpose: Influences commission calculations and transaction routing

Chunk 11: Cancellation Subfolder Components
Metadata: subfolder=Cancellations, components=4, purpose=cancellationWorkflow

MapCancellation Lambda: Orchestrates credit memo creation
MapCancellationRefund Lambda: Refund-specific logic
PolicyCancelRefundAdjustmentDto: DTO with credit memo references, refund amounts, recipients
InsurancePolicyCancelledEventPayload: Event model with policy/account identifiers, cancellation reasons, dates, other interests, billing type, coverage blocks, unearned premium, sales tax refund

Chunk 12: Event Domain Models
Metadata: subfolder=Events, type=payloadModels, count=10+, compliance=PII

PolicyIssuedEventV2Payload: New policy event with account, policy, product, premium, coverage, billing, producer info
InsurancePolicyRenewedEventPayload: Extends issuance payload, adds AgencyFirstWrittenDate
CommissionDisbursementCreditedPayload: Commission payment events
PolicyEventBase: Base class for policy events
PII Compliance: Uses attributes on sensitive fields

Chunk 13: Transaction Type Determination
Metadata: concept=transactionTypeMapping, factors=BillingType+OtherInterests, values=Internal/External
Internal: BillingType="OtherInterest" AND OtherInterests contains InternalLender=true
External: All other cases
Transaction Codes: HfaInvoiceInternal/External for invoices; Credit Memos vary by operation with Int/Ext suffix

Chunk 14: Memo Line Integration Pattern
Metadata: integration=MemoLineLookup, purpose=GLMapping, timing=temporal
Lookup Pattern: IMemoLookup.GetMemoLookupAsync using invoice creation date
Filtering: By Action, Type, ProductType, Organization, State, Commission Percent
GL Assignment: MemoLine.Description → TransactionLine.MemoLine; distribution % → amount
Temporal Guarantee: Historical accuracy, unaffected by configuration changes

Chunk 15: Transaction Line Sorting
Metadata: component=TransactionLineComparer, type=comparator, purpose=lineOrdering
Sort Order:

Premium Lines (Assurant Payable first)
Commission Lines
Fee Lines
Other Lines (original order)
Post-Sort: Renumber LineNumber sequentially
Purpose: Consistent invoice presentation, supports downstream processing

Chunk 16: DTO Folder Components
Metadata: subfolder=Dto, type=dataTransferObjects, count=6+, purpose=lambdaInputs

MapEndorsementAdjustmentsDto: Installments, OpenBalance, AdjustmentConfiguration
PolicyRenewedInvoiceMaptDto: PolicyRenewedEvent, Customer, LicenseInfo, PreviousInvoice
RenewedGetLicensingDto: PolicyRenewedEvent, PreviousInvoice
NonMonetaryEndorsementUpdateDto: OldCustomer, Updates collection
PolicyCancelRefundAdjustmentDto: Refund-specific data
Pattern: DTOs implement deconstruction methods for tuple unpacking

Chunk 17: Coverage Block Processing
Metadata: concept=coverageBlocks, purpose=premiumAllocation, granularity=perCoverage
Structure: CoverageBlock → Code, Coverage, Premium
Usage: Cancellations → pro-rated unearned premium; endorsements → coverage-specific adjustments; invoice generation → allocates premiums per coverage
GL Distribution: Different coverage types route to GL accounts via memo line config

Chunk 18: Commission Metadata Enrichment
Metadata: operation=commissionEnrichment, fields=7, differentiation=RetailVsHFA
Common Fields: BusinessGroup, NewOrRenewal, CommissionPercent, AgencyFirstWrittenDate
Retail: CommissionOrganization="Clayton Retail", Producer, SubProducer, CommissionReference
HFA: CommissionOrganization="HFA", Producer, SubProducer=empty, CommissionReference=empty
Detection: MemoLine.Description contains "Retail Commission" or "HFA Commission"
Renewal: Copies AgencyFirstWrittenDate

Chunk 19: State and Jurisdiction Handling
Metadata: concept=stateCodeProcessing, normalization=descriptionConversion, usage=memoLineFiltering
State Sources: PhysicalStateCode → string description via ToDescription()
Memo Line Filtering: State description used in GetMatchingLines
Address Normalization: State codes → descriptions
Tax Implications: State drives sales tax/refund in cancellations

Chunk 20: Search Queries Supported
Metadata: type=queryPatterns, purpose=RAGRetrieval
Sample Queries:

"How are policy issuance invoices created in Oracle?"
"What is the commission calculation process?"
"How do cancellations generate credit memos?"
"What adjustment types are supported for refunds?"
"How are endorsement balance changes distributed?"
"How do non-monetary endorsements update customers?"
"Transaction types for internal vs external billing?"
"How are coverage blocks used in premium calculations?"
"Memo line filtering criteria for invoices?"
"How does licensing service determine dealer numbers?"
"Transaction line sorting order on invoices?"
"How are policy renewal invoices different from issuance?"
"Cancellation reasons mapping?"
"How do refunds distribute to Retail, VMF, or customers?"
"Validation on invoice selection?"
"How does temporal memo line lookup work?"
"Which fields are updateable via non-monetary endorsements?"
"Commission organization determination (Retail vs HFA)?"
"How does system handle internal lenders for transaction typing?"