Common Module – Optimized RAG Knowledge Base

Chunk 1: Module Overview
Metadata: module=Common, type=sharedKernel, location=CMH.HFA.Accounting.Orchestration/src/Common, domain=insuranceDomain, pattern=valueObjects, count=2
Purpose: Shared kernel domain models representing core insurance business concepts used across multiple bounded contexts.
Scope: Two lightweight domain models for coverage information and lender relationships, with no business logic or external dependencies.
Design Pattern: Shared kernel consumed by multiple modules (BillingChange, Policy, Cancellations, Endorsement)
Key Concepts: Coverage block representation, lender interest tracking, internal vs external lender classification, premium allocation, multi-coverage policies

Chunk 2: CoverageBlock Model
Metadata: model=CoverageBlock, type=valueObject, location=Common/Model, purpose=coverageRepresentation, granularity=perCoverage
Description: Represents a single insurance coverage item within a policy for granular premium tracking and allocation.
Properties:

Code: Coverage type identifier or classification code
Coverage: Decimal coverage amount or limit
Premium: Decimal premium for this coverage block
Purpose: Enables multi-coverage policy representation, pro-rated refund calculations, and coverage-specific premium allocation
Mutability: Simple get/set properties

Chunk 3: CoverageBlock Use Cases
Metadata: useCases=CoverageBlock, consumers=3+, scenarios=multiCoverage

Policy Cancellations: Enables unearned premium calculations and pro-rated refunds when partial coverage canceled
Policy Issuance: Tracks original coverage composition
Premium Distribution: Allocates GL accounts based on coverage type codes
Refund Calculations: Distribute unearned premium proportionally
Example: Policy with Collision ($800), Comprehensive ($300), Liability ($100) tracked as three CoverageBlock instances

Chunk 4: OtherInterest Model
Metadata: model=OtherInterest, type=valueObject, location=Common/Model, purpose=lenderTracking, classification=InternalExternal
Description: Represents third-party financial interests in a policy (lenders or financing entities).
Properties:

LenderCode: Unique lender identifier
Name: Lender name
OtherInterestUniqEntity: Integer unique entity ID
InternalLender: Boolean (internal organization lender vs external)
Purpose: Tracks financial stakeholders, drives transaction type routing, affects GL account selection

Chunk 5: OtherInterest Use Cases
Metadata: useCases=OtherInterest, consumers=billingAndCancellation, impactArea=transactionTyping

Billing Type Determination: Used in BillingTypeChangeLambda to identify billing type transitions
Transaction Classification: Internal vs External based on InternalLender flag
Policy Cancellations: Tracks lender interests for cancellations
Refund Routing: Determines intercompany vs customer refund routing
GL Account Selection: Internal vs External affects GL codes (e.g., HfaCmTypeChgInt vs HfaCmTypeChgExt)

Chunk 6: Internal Lender Business Logic
Metadata: concept=internalLenderLogic, impact=transactionTyping, codes=IntVsExt
Logic: BillingType = "OtherInterest" AND any OtherInterest.InternalLender=true → Internal transaction
Else → External
Transaction Codes:

Internal Invoice: HfaInvoiceInternal, HfaInvTypeChgInt, etc.
External Invoice: HfaInvoiceExternal, HfaInvTypeChgExt, etc.
Internal Credit Memo: HfaCmEndorseInt, HfaCmTypeChgInt, etc.
External Credit Memo: HfaCmEndorseExt, HfaCmTypeChgExt, etc.
Purpose: Routes transactions to appropriate GL accounts based on lender relationship

Chunk 7: Namespace and Location
Metadata: namespace=Accounting.Orchestration.Common.Model, accessibility=public, dependencies=none
Namespace: Accounting.Orchestration.Common.Model
Access Modifier: Classes are public
Dependencies: None beyond .NET primitives (string, decimal, int, bool)
Import Pattern: using Accounting.Orchestration.Common.Model;
Design Principle: Dependency-free shared kernel reduces coupling

Chunk 8: Data Transfer Characteristics
Metadata: pattern=DTOs, serialization=supported, immutability=mutable
DTO Pattern: Models act as simple property bags
Serialization: Compatible with JSON.NET or System.Text.Json
Immutability: Mutable get/set properties
Behavior: No methods or validation; pure data structures
Event Usage: Included in PolicyIssuedEvent, CancellationEvent, etc.

Chunk 9: Module Consumption Pattern
Metadata: consumers=multiModule, count=4+, sharingScope=orchestration
Consumers: BillingChange, Policy, Cancellations, Endorsement
Sharing Scope: Orchestration project only
Access Pattern: Modules reference Common.Model namespace; receive models via deserialization
Design Rationale: Avoid duplication of core insurance concepts

Chunk 10: Evolution and Stability
Metadata: stability=high, evolutionRate=low, backwardCompatibility=critical
Stability: Models represent fundamental insurance concepts, unlikely to change
Change Impact: Affects multiple modules, requires coordinated updates
Backward Compatibility: Additions safe; removals/renames need coordination
Extension: Add new properties or new model files in Common/Model

Chunk 11: Coverage Type Taxonomy
Metadata: concept=coverageTypes, examples=provided, extensibility=open
Common Types: Collision, Comprehensive, Liability, ESC, Gap, VSC
Code Property: Maps to product codes or coverage classification
Variable Count: 1-N CoverageBlocks per policy
Premium Aggregation: Total policy premium = sum of coverage block premiums
Use: Pro-rating, refunds, GL allocation

Chunk 12: Lender Relationship Examples
Metadata: examples=lenderScenarios, scenarios=3, realWorld=true

Internal Financing: OtherInterest.InternalLender=true → Internal transaction
External Financing: OtherInterest.InternalLender=false → External transaction
Cash Purchase: No financing → defaults to External
Multiple Lenders: Any single internal lender triggers Internal classification

Chunk 13: Validation and Business Rules
Metadata: validation=none, businessRules=consumer, enforcement=external
Validation: None at model level
Business Rule Enforcement: By consuming services
Null Handling: Properties allow null; consumers must check
Defaults: No constructor initialization; properties default to type defaults
Design: Simple models, push logic to service layer

Chunk 14: Integration with Event Models
Metadata: integration=eventPayloads, eventTypes=3+, composition=nested
PolicyIssuedEventV2Payload: List<OtherInterest>, List<CoverageBlock>
InsurancePolicyCancelledEventPayload: List<OtherInterest>, List<CoverageBlock>
Nested Structure: Common models embedded in event payloads
Serialization Flow: JSON serialization/deserialization for EventBridge/SQS/SNS
Purpose: Consistent data across event-driven workflows

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

"What models are in the Common module?"
"What is a CoverageBlock?"
"How are coverage blocks represented?"
"What is the OtherInterest model used for?"
"How do I determine if a lender is internal or external?"
"What properties does CoverageBlock contain?"
"How does InternalLender flag affect transaction types?"
"What modules consume the Common models?"
"How are Common models serialized in events?"
"What is the shared kernel pattern in Common module?"