Services Module – RAG Knowledge Base

Chunk 1: Module Overview
Metadata: module=Services, type=overview, location=CMH.HFA.Accounting.Orchestration/src/Services, count=1
Purpose: Lambda function wrapper layer for adjustment configuration management
Scope: Single service class providing CRUD for Oracle receivables adjustment configurations stored in DynamoDB
Integration Points: Consumed by endorsement processing workflows, refund adjustment workflows, policy cancellation services
Key Concepts: adjustment configuration, receivables transaction mapping, Lambda endpoints, configuration retrieval and persistence

Chunk 2: AdjustmentConfigService Class
Metadata: component=AdjustmentConfigService, type=service, pattern=repository-wrapper, deployment=Lambda
Description: Exposes three Lambda endpoints for managing Oracle adjustment configurations
Base Class: Extends BaseLambdaService for Lambda integration and service resolution
Dependencies: IAdjustmentConfigRepository for data access
Constructor Pattern: Dual constructors – parameterless for Lambda runtime, parameterized for dependency injection in tests
Lambda Configuration: Uses LambdaFunction annotation for AWS Lambda deployment metadata

Chunk 3: GetConfigurations Operation
Metadata: operation=GetConfigurations, httpMethod=N/A, returnType=IList<AdjustmentConfigurationModel>, filtering=none
Purpose: Retrieves all adjustment configuration records without filtering
Parameters: None
Returns: Complete collection from DynamoDB
Use Case: Admin audits, bulk export, dropdown population
Behavior: Pass-through to repository GetAllAdjustmentConfigurationsAsync with no business logic

Chunk 4: GetConfiguration Operation
Metadata: operation=GetConfiguration, filtering=multi-criteria, returnType=AdjustmentConfigurationModel, nullable=true
Purpose: Retrieves single adjustment configuration by Name and Type with active status validation
Parameters: GetAdjustmentConfigurationDto (Name, Type)
Filtering Logic: Case-insensitive match on Name AND Type, active status evaluated via IsActive
Validation: Null DTO check, required Name/Type validation, multi-error accumulation
Use Case: Workflow-driven lookup for specific receivables transaction type

Chunk 5: SaveAsync Operation
Metadata: operation=SaveAsync, mutationType=replace-all, transactional=true, rollback=automatic
Purpose: Persists full collection of adjustment configurations using replace-all pattern
Parameters: IList<AdjustmentConfigurationModel> collection
Validation: Non-null, non-empty collection; throws ArgumentException if invalid
Behavior: Delegates to repository SaveAdjustmentConfigurationsAsync which deletes all existing records, inserts new ones in parallel, automatically rolls back on failure
Use Case: Bulk configuration refresh, migration, environment updates

Chunk 6: AdjustmentConfigurationModel Structure
Metadata: model=AdjustmentConfigurationModel, storage=DynamoDB, keyType=composite
Keys: Hash key = Id (Guid), Range key = ReceivableTrxId (Oracle transaction type)
Oracle Integration Properties:

ReceivableTrxId: AR receivables transaction type ID
OrgId: Oracle org ID for multi-org
SetOfBooksId: Oracle ledger/set of books ID
Configuration Properties:
Name: Human-readable identifier
Type: Category (e.g., Refund, Endorsement)
Temporal Properties: IsActiveFlag (boolean), StartActiveDate, InactiveDate, EndActiveDate

Chunk 7: Active Status Evaluation
Metadata: method=IsActive, type=businessRule, timezone=UTC
Logic: Multi-condition temporal and flag-based evaluation
Returns False if:

Current UTC < StartActiveDate
Current UTC ≥ InactiveDate
Current UTC ≥ EndActiveDate
IsActiveFlag = false
Returns True if all temporal boundaries satisfied AND IsActiveFlag = true
Date Parsing: DateTime.TryParse with graceful handling of unparseable dates

Chunk 8: GetAdjustmentConfigurationDto
Metadata: dto=GetAdjustmentConfigurationDto, purpose=queryInput, validation=required
Properties: Name (string, required), Type (string, required)
Validation: Both non-null/non-empty; violations thrown as ArgumentException with concatenated messages
Usage: Passed as Lambda input, deserialized from JSON request, validated before lookup
Example: Name="HFA Auto Customer Refund", Type="Refund"

Chunk 9: Configuration Categories
Metadata: concept=configurationTypes, domain=adjustments
Refund Types:

HFA Retail I/C Refund: Intercompany refunds to Retail org
HFA VMF I/C Refund: Intercompany refunds to VMF org
HFA Auto Customer Refund: Direct customer refunds
Endorsement Types: For endorsement adjustment receivables
Purpose: Determines which Oracle receivables transaction ID, org routing, and GL treatment applies
Selection Logic: Based on refund recipient or adjustment nature

Chunk 10: Integration Workflows
Metadata: type=useCases, consumers=multipleWorkflows
Endorsement Adjustment Workflow: Retrieves endorsement config, creates Adjustment records with correct Oracle IDs
Policy Cancellation Refund Workflow: Retrieves refund config, creates Adjustment record, applies to credit memo
Configuration Management: Admin workflows retrieve and save configurations with automatic rollback
Lambda Orchestration: Step Functions invoke these Lambda endpoints as discrete workflow steps

Chunk 11: Error Handling Patterns
Metadata: concept=errorHandling, pattern=validation-first
Validation Strategy: Fail-fast with comprehensive messages, multi-error accumulation
Error Types:

ArgumentNullException: DTO null in GetConfiguration
ArgumentException: Missing Name/Type, empty collection in SaveAsync
Repository Exceptions: Propagated from DynamoDB layer
Rollback Handling: SaveAsync automatically rolls back on repository failure

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

"How do I retrieve Oracle adjustment configuration by name and type?"
"What is the structure of adjustment configuration records?"
"How does active status evaluation work for configurations?"
"What Lambda functions are available for configuration management?"
"How do I persist adjustment configurations?"
"What rollback protection exists for configuration saves?"
"What Oracle properties are stored in adjustment configurations?"
"How are refund configurations categorized?"
"What validation is performed on configuration retrieval?"
"How do endorsement workflows use adjustment configurations?"
"What is the difference between Retail, VMF, and Customer refund configurations?"
"How does temporal validity work for adjustment configurations?"