160 lines
8.1 KiB
Plaintext
160 lines
8.1 KiB
Plaintext
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?" |