System Architecture
Core Features
Data Management
Frontend Components
Extensibility
The following files were used as context for generating this wiki page:
The "IntegrationPlatformTestPage -> UpdateStatus" flow describes the process initiated when a user attempts to test an existing integration connection from the Integration Platform Test Page. This flow validates the connection's credentials (e.g., AWS IAM role and Security Hub status) and subsequently updates the connection's status in the database to either active (if successful) or error (if validation fails), along with a descriptive error message.
This process is crucial for ensuring the health and validity of integrated services, providing immediate feedback to users about their connection's operational status. It helps identify misconfigurations or permission issues proactively, preventing downstream failures in data synchronization or automated checks.
Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:1-550, apps/api/src/integration-platform/controllers/connections.controller.ts:1-748
The process begins on the IntegrationPlatformTestPage (apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx), a client-side React component. This page displays a list of integration connections. When a user clicks the "Test" button associated with a specific connection, it triggers the handleTestConnection function. This function captures the connectionId and providerSlug for the connection to be tested.
The handleTestConnection function (apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx) sets a loading state and logs the action to the UI. It then calls the testConnection mutation (provided by useIntegrationMutations), which internally makes an API call to the backend. This call is typically a POST request to /v1/integrations/connections/:id/test, sending the to the API.
Sources: apps/app/src/app/(app)/[orgId]/integrations/platform-test/page.tsx:392-400, apps/api/src/integration-platform/controllers/connections.controller.ts:499-668, apps/api/src/integration-platform/services/connection.service.ts:104-110, apps/api/src/integration-platform/services/connection.service.ts:112-117, apps/api/src/integration-platform/repositories/connection.repository.ts:121-131
This flow demonstrates a robust mechanism for validating and updating integration connection statuses, spanning multiple architectural layers.
Cross-Module Boundaries: The execution crosses significant boundaries:
IntegrationPlatformTestPage triggers an API call to the ConnectionsController.ConnectionsController delegates business logic to the ConnectionService and CredentialVaultService.ConnectionService interacts with the ConnectionRepository for database operations.ConnectionsController directly interacts with external AWS SDKs (STS, SecurityHub) to perform real-time credential validation. This is a critical external dependency.Potential Failure Points and Handling:
handleTestConnection function includes try-catch blocks to log errors.ConnectionsController and ConnectionService validate the existence of the connection and its credentials. Missing credentials or an invalid connection ID will result in or .The AWS credential validation (validateAwsCredentials) is a critical external dependency. Any issues with AWS services, network connectivity to AWS, or misconfigurations of the internal SECURITY_HUB_ROLE_ASSUMER_ARN environment variable could lead to validation failures, even if the customer's credentials are correct.
testConnection operation potentially slow.findById, findBySlug) occur. These are generally fast but contribute to the overall latency.refreshConnections() is called on the client, which refetches all connections. This ensures the UI is up-to-date but adds another round trip.Sources: apps/api/src/integration-platform/controllers/connections.controller.ts:499-668, apps/api/src/integration-platform/services/connection.service.ts:104-117, apps/api/src/integration-platform/repositories/connection.repository.ts:121-131
connectionIdThe testConnection method in ConnectionsController (apps/api/src/integration-platform/controllers/connections.controller.ts) receives the API request. It first retrieves the IntegrationConnection object from the database using the provided connectionId. It then fetches the decrypted credentials associated with this connection from the credentialVaultService.
The controller checks the providerSlug of the connection. For specific providers like AWS, it delegates to a specialized testing method (testAwsConnection). For other providers, it attempts to use a testConnection handler defined within the provider's manifest, if available. If no specific handler exists, it defaults to activating the connection.
For AWS connections, the testAwsConnection method (apps/api/src/integration-platform/controllers/connections.controller.ts) is invoked. This method performs a comprehensive validation:
roleArn, externalId, and regions from the connection's credentials.roleArn) with the externalId. This verifies the IAM role's validity and permissions.The result of this validation (success or failure) is returned, along with a detailed message.
If the validation in testAwsConnection (or any other provider's test handler) fails, the setConnectionError method in ConnectionService (apps/api/src/integration-platform/services/connection.service.ts) is called. This method is a convenience wrapper that prepares the connection for an error state. It takes the connectionId and an errorMessage as input.
The setConnectionError method (or activateConnection in case of success) internally calls updateConnectionStatus in ConnectionService (apps/api/src/integration-platform/services/connection.service.ts). This method is responsible for orchestrating the status update. It first performs a check to ensure the connection exists by calling getConnection(connectionId). If the connection is found, it proceeds to call the repository layer to persist the status change.
Finally, the updateStatus method in ConnectionRepository (apps/api/src/integration-platform/repositories/connection.repository.ts) is invoked. This method directly interacts with the database. It updates the status field of the IntegrationConnection record corresponding to the connectionId to either active or error, and also stores the errorMessage if provided. This completes the backend process, and the updated status is then reflected in the frontend after the refreshConnections call.
NotFoundExceptionBadRequestExceptionvalidateAwsCredentials handles various AWS-specific errors:
sts:AssumeRole.AccessDenied errors will occur.error with a user-friendly message.testConnection handler throws an error or returns false, the connection status is set to error.updateStatus in the ConnectionRepository could occur, though typically handled by the ORM/database layer.