Integrations Module – RAG Knowledge Base

Chunk 1: Module Overview
Metadata: module=Integrations, type=infrastructure, location=CMH.HFA.Accounting.Orchestration/src/Integrations, pattern=baseClasses, purpose=externalSystemConnectivity
Purpose: Foundational infrastructure for reusable HTTP client patterns, authentication, and configuration for external system integration
Scope: Two base classes for Oracle Cloud Integration (OIC) and on-prem HFA APIs
Stack: Flurl.Http for HTTP, AWS Secrets Manager for credentials, environment-based configuration
Key Concepts: Integration abstraction, secret management, HTTP client configuration, environment-aware URL construction, authentication patterns, base class inheritance

Chunk 2: OracleIntegrationBase Class
Metadata: component=OracleIntegrationBase, type=abstractBaseClass, integration=OracleCloudIntegration, authentication=BasicAuth, location=Integrations/Oracle
Description: Abstract base for OIC API clients, providing authenticated HTTP requests
Authentication: HTTP Basic Auth with username/password from AWS Secrets Manager
Base URL: https://erp-{oicEnv}-oicintegration-idq4hj6bgo2f-ia.integration.ocp.oraclecloud.com
Protected Method: GetRequestAsync(endpoint) returns pre-configured IFlurlRequest
Inheritance: Derived classes implement specific services (e.g., MemoLookup)

Chunk 3: Oracle Secret Management
Metadata: secrets=OracleCredentials, storage=AWSSecretsManager, count=3, pattern=environmentSpecific
Secrets:

Username: {ENVIRONMENT}-hfa-oic-username
Password: {ENVIRONMENT}-hfa-oic-password
OIC Environment: {ENVIRONMENT}-hfa-oic-environment
Retrieval: ISecretString service, async during request creation
Environment Isolation: Separate credentials per deployment environment
Purpose: Centralized credential management, supports rotation

Chunk 4: BaseOnPremIntegration Class
Metadata: component=BaseOnPremIntegration, type=concreteBaseClass, integration=HFAOnPremises, authentication=ClientCredentials, location=Integrations
Description: Base class for on-prem HFA services using client ID/secret headers
Authentication: Custom headers (client-id and client-secret)
URLs:

Prod: https://dat.homefirstagency.com
Non-prod: https://dat.{environment}.homefirstagency.com
Protected Methods: GetRequestAsync(), UpdateEndpoint(flurlRequest, endpoint)
Caching: Flurl request cached for service instance lifetime

Chunk 5: On-Premises Secret Management
Metadata: secrets=OnPremCredentials, storage=AWSSecretsManager, count=2, authentication=clientCredentials
Secrets:

Client ID: {ENVIRONMENT}-hfa-licensing-api-client-id
Client Secret: {ENVIRONMENT}-hfa-licensing-api-client-secret
Header Format: Passed as custom headers
Service Name Pattern: Constructor accepts serviceName for named HTTP client
Purpose: Supports internal HFA API key authentication, enables per-service configuration

Chunk 6: Environment Variable Handling
Metadata: configuration=environmentVariables, required=ENVIRONMENT, validation=constructor, failureBehavior=exception
Required Variable: ENVIRONMENT (dev, test, prod)
Validation: Both base classes validate in constructor, fail-fast if missing
Usage: Drives secret key construction, URL routing, table patterns
Purpose: Ensures environment isolation, prevents misconfiguration

Chunk 7: HTTP Client Factory Integration
Metadata: pattern=HttpClientFactory, scope=OnPremOnly, dependency=IHttpClientFactory, namedClients=supported
Pattern: BaseOnPremIntegration uses IHttpClientFactory, named client via serviceName
OracleIntegrationBase: Direct Flurl request creation, no HttpClientFactory
Purpose: Centralized HTTP client configuration, supports ASP.NET Core best practices

Chunk 8: Request Caching Strategy
Metadata: optimization=caching, scope=OnPremOnly, pattern=lazy, field=_flurlRequest
Caching: Flurl request cached for service instance lifetime
OracleIntegrationBase: No caching, new request each call
Benefit: Reduces secret retrieval overhead, improves performance

Chunk 9: URL Construction Patterns
Metadata: concept=urlConstruction, components=2, patterns=environmentBased
Oracle URL: Base from secret (oicEnv), endpoint concatenation via string addition
On-Prem URL: Subdomain routing based on ENVIRONMENT, endpoint appended via UpdateEndpoint
Purpose: Environment-specific API routing without code changes

Chunk 10: Known Implementations
Metadata: implementations=derived, count=1known, location=StructuredTags
Oracle: MemoLookup service (GL account memo line configs), implements IMemoLookup
On-Prem: Expected – Licensing API, dealer info, sales data, policy lookup
Pattern: Inherit base class, add endpoint methods, deserialize responses

Chunk 11: Dependency Injection Patterns
Metadata: pattern=dependencyInjection, dependencies=2, testability=high
Common: ISecretString for secret access
On-Prem Additional: IHttpClientFactory + serviceName
Oracle Minimal: Only ISecretString
Purpose: SOLID-compliant, supports unit and integration testing with mocks

Chunk 12: Authentication Comparison
Metadata: comparison=authenticationMethods, methods=2, security=secretBased
Oracle: HTTP Basic Auth (Authorization: Basic {base64(username:password)})
On-Prem: Custom headers (client-id, client-secret)
Security: Both retrieve secrets from AWS Secrets Manager, no hardcoding, environment-isolated

Chunk 13: Extensibility Patterns
Metadata: pattern=extensibility, method=inheritance, examples=provided
Steps: Inherit base class → inject dependencies → call base constructor → add endpoint methods → use GetRequestAsync() → deserialize responses
Example: CustomerIntegration : OracleIntegrationBase, DealerIntegration : BaseOnPremIntegration
Purpose: Code reuse, consistent auth, standard integration patterns

Chunk 14: Error Handling Patterns
Metadata: errorHandling=exceptions, validation=constructor, propagation=upstream
ENV Errors: Throws generic exception if ENVIRONMENT missing
Secret Retrieval: Exceptions propagate, no catch
HTTP Errors: Base classes do not handle; derived classes responsible
Null Handling: MemoLookup throws ArgumentNullException for null deserialization
Pattern: Fail-fast, let exceptions bubble

Chunk 15: Integration Use Cases
Metadata: useCases=multiple, frequency=perTransaction, criticality=high

Memo line lookups (GL account mappings per transaction)
Customer queries (Oracle data retrieval)
Invoice posting (Oracle endpoints)
Payment processing (Oracle integrations)
Licensing queries (on-prem)
Sales data retrieval (on-prem)
Frequency: High for memo lookups, lower for licensing/sales queries

Chunk 16: Design Benefits
Metadata: benefits=architectural, principles=SOLID, maintainability=high

Single Responsibility: One base class per integration type
DRY: Centralized auth/config logic
Testability: Dependency injection
Maintainability: Auth changes require only base class updates
Scalability: Easy to extend
Security: Secrets never hardcoded
Environment Safety: Environment-isolated credentials

Chunk 17: Flurl HTTP Library Features
Metadata: library=Flurl, features=utilized, purpose=fluentAPI

Fluent request building: WithHeader(), WithBasicAuth()
URL construction: string concatenation
Response handling: GetAsync(), GetStringAsync()
Client configuration: FlurlClient wrapper
Usage: Base classes return IFlurlRequest for derived execution

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

"How do I integrate with Oracle Cloud Integration from Lambda?"
"What base class should I use for Oracle OIC integration?"
"How are Oracle credentials managed?"
"What authentication method is used for on-prem HFA services?"
"How do I create a new Oracle integration?"
"What secrets are needed for Oracle integration?"
"How does environment-based URL routing work?"
"Difference between Oracle and on-prem integration classes?"
"How do I implement a new on-prem service client?"
"What HTTP client library is used for integrations?"
"How are credentials retrieved?"
"What environment variables are required?"
"How does request caching work on-prem?"
"What dependency injection is required?"
"How do I extend OracleIntegrationBase for a new endpoint?"
"What error handling patterns are used?"
"How does memo lookup use Oracle integration?"
"What benefits does the integration base class provide?"