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<AdjustmentConfigurationModel>
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?"