Repository Module – RAG Knowledge Base Chunk 1: Module Overview Metadata: module=Repository, actualFolder=Respository, type=dataAccess, location=CMH.HFA.Accounting.Orchestration/src/Respository, storage=DynamoDB, count=2 Purpose: Data access layer implementing repository patterns for DynamoDB persistence Scope: Two repositories – FIFO event queue and adjustment configuration storage Technology Stack: AWS DynamoDB SDK, DynamoDB DataModel context, Task.WhenAll for parallel operations, conditional updates for concurrency control Key Concepts: repository pattern, data access abstraction, DynamoDB document model, environment-based table naming, optimistic concurrency, TTL cleanup Chunk 2: DynamoDbFifoRepository Class Metadata: component=DynamoDbFifoRepository, interface=IFifoRepository, purpose=eventQueuePersistence, pattern=FIFO Description: Manages FIFO event queue infrastructure with policy-based partitioning Table Structure: Partition key = PolicyNumber, Sort key = Timestamp (ISO 8601), GSI = EventId Table Naming: {ENVIRONMENT}-fifo-poc-table pattern Operations: Event retrieval by ID via GSI, policy-scoped queries, persistence, atomic status updates Concurrency Control: ConditionalCheckFailedException prevents race conditions Chunk 3: FIFO Event Retrieval Operations Metadata: operation=GetEventByIdAsync, indexType=GSI, indexName=EventIdIndex, returnType=EventTableEntry Purpose: Retrieves single event by EventId using GSI Parameters: Guid eventId Query Behavior: Limits to 1 record, returns null if not found Use Case: Completion workflows or dequeue operations Performance: O(1) lookup via GSI, no full table scan Chunk 4: FIFO Policy-Scoped Queries Metadata: operation=QueryByPolicyNumberAsync, keyType=partitionKey, filtering=optional, consistency=strong Purpose: Retrieves all events for a policy number, optional status filter Parameters: policyNumber, statusFilter Query Behavior: Partition key query with optional filter expression, consistent reads Use Case: FIFO service checking queue depth, next pending event, validating no events in processing Chunk 5: FIFO Event Persistence Metadata: operation=SaveEventAsync, mutationType=insert, conflicts=allowDuplicates Purpose: Saves new event entry to DynamoDB FIFO table Parameters: EventTableEntry (PolicyNumber, Timestamp, EventId, Status, EventBody, DeduplicationKey) Behavior: Simple save, allows concurrent inserts, deduplication handled at service layer Use Case: Enqueue events for processing Chunk 6: FIFO Status Updates Metadata: operation=UpdateStatusAsync, atomicity=conditional, concurrencyControl=optimistic Purpose: Updates event status with optional conditional check Parameters: policyNumber, timestamp, status, expectedStatus (optional) Conditional Path: Conditional expression requires current status match; throws ConditionalCheckFailedException on mismatch Unconditional Path: Loads entity, updates status, sets TTL if COMPLETED TTL Logic: 30-day expiry for automatic cleanup Chunk 7: AdjustmentConfigRepository Class Metadata: component=AdjustmentConfigRepository, interface=IAdjustmentConfigRepository, purpose=configurationStorage, pattern=replace-all Description: Manages Oracle adjustment configuration records in DynamoDB Table Structure: Hash key = Id (Guid), Range key = ReceivableTrxId Table Naming: {ENVIRONMENT}-hfa-adjustement-configuration-table (note typo) Operations: Full table scan retrieval, transactional replace-all persistence Parallelization: Task.WhenAll for concurrent deletes and inserts Chunk 8: Configuration Retrieval Metadata: operation=GetAllAdjustmentConfigurationsAsync, scanType=fullTable, parallelization=true Purpose: Retrieves all adjustment configurations Scan Strategy: Full table scan, parallel deserialization with Task.Run Return Type: IList Use Case: Configuration lookup, admin display, filtering in service layer Chunk 9: Configuration Persistence with Rollback Metadata: operation=SaveAdjustmentConfigurationsAsync, pattern=deleteAllThenInsert, transactional=applicationLevel, rollback=automatic Purpose: Replaces full table contents using application-level transaction Steps: Backup → Delete all → Insert new → Rollback on failure Atomicity: Application-level (not DynamoDB transaction), temporary empty table during delete-to-insert Use Case: Bulk updates, configuration migration Chunk 10: Environment Configuration Metadata: concept=environmentVariables, required=true, validation=startup Requirement: Environment variable must be set (dev/test/prod) Validation: Repositories throw Exception if missing Table Naming Patterns: FIFO: {ENVIRONMENT}-fifo-poc-table Adjustment Config: {ENVIRONMENT}-hfa-adjustement-configuration-table Purpose: Environment isolation, multi-environment deployments Chunk 11: DynamoDB Context Configuration Metadata: concept=dynamoDBConfiguration, pattern=tableOverrides Configuration Objects: GetTargetTableConfig, FromDocumentConfig, LoadConfig, SaveConfig, DeleteConfig Override Pattern: OverrideTableName allows environment-specific routing Initialization: Configs created in constructor, reused for efficiency Chunk 12: TTL (Time To Live) Implementation Metadata: feature=TTL, storage=DynamoDB, duration=30days, scope=completedEvents Purpose: Automatic cleanup of completed FIFO events TTL Field: TimeToLive (Unix timestamp) Calculation: DateTimeOffset.UtcNow.AddDays(30).ToUnixTimeSeconds() Trigger: Set on status COMPLETED, ignored for PENDING/PROCESSING DynamoDB Behavior: Deletes within ~48 hours, no cost Chunk 13: Concurrency Patterns Metadata: concept=concurrencyControl, mechanism=conditionalUpdates, exception=ConditionalCheckFailedException FIFO Updates: Conditional expressions prevent multiple Lambda instances from transitioning same event Expected Status Pattern: Ensures current status matches expected before updating Race Conditions: Multiple Lambda cold starts, rapid event arrivals, completion races Exception Handling: Catch and ignore, losing instance backs off gracefully Chunk 14: Parallel Processing Optimization Metadata: optimization=parallelization, mechanism=TaskWhenAll, scope=bulkOperations Adjustment Config Retrieval: Parallel deserialization Delete Operations: Parallel delete of existing configs Insert Operations: Parallel save of new configs Trade-offs: Higher Lambda memory, faster wall-clock time, rollback handles partial failures Chunk 15: Search Queries Supported Metadata: type=queryPatterns, purpose=RAGRetrieval Sample Queries: "How do I retrieve FIFO events by policy number?" "What is the repository pattern implementation for DynamoDB?" "How does conditional update work for FIFO event status?" "What table naming convention is used for repositories?" "How is TTL configured for completed events?" "What rollback mechanism exists for configuration saves?" "How do I query events by event ID?" "What concurrency control is used in FIFO repository?" "How are adjustment configurations stored in DynamoDB?" "What happens when environment variable is missing?" "How does parallel processing work in repositories?" "What is the Global Secondary Index structure for FIFO events?" "How long are completed events retained in DynamoDB?" "What exception indicates a race condition in status updates?"