Skip to content

Microservices

Target Architecture — Final-State Design

This page enumerates the final-state microservice topology of the Integration Platform. Each service is an independently deployable .NET 10 / ASP.NET Core application following Clean Architecture + DDD, messaging over MassTransit on Azure Service Bus, persisting via NHibernate against Azure SQL / PostgreSQL, custodying credentials in Azure Key Vault, and instrumented with ConnectSoft.Extensions.Observability (Serilog + OpenTelemetry + Application Insights).

The Integration Platform comprises 14 microservices in the ConnectSoft.Factory.Integration.* namespace. Each owns its aggregates and store, exposes behaviour through REST/gRPC and the canonical event envelope, and scales independently per tenant and provider load. Services never share a database; cross-service flow is event-driven. Several services compose existing reusable clients and extensions, marked Implemented below.

Service Catalog

Microservice Responsibility APIs Key Events Aggregate Roots Store
AzureDevOpsIntegrationService Drive Azure DevOps repos, PRs, pipelines, and checks POST /integrations/connections, GET /integrations/runs/{runId} IntegrationConnectionEstablished, IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationRun Azure SQL / PostgreSQL (NHibernate)
GitHubIntegrationService Drive GitHub repos, PRs, Actions, and checks POST /integrations/connections, GET /integrations/runs/{runId} IntegrationConnectionEstablished, IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationRun Azure SQL / PostgreSQL
OpenAIIntegrationService Govern access to OpenAI completion/embedding APIs (internal gRPC) IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationRun Azure SQL / PostgreSQL
AzureOpenAIIntegrationService Govern access to Azure OpenAI deployments (internal gRPC) IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationRun Azure SQL / PostgreSQL
OllamaIntegrationService Front self-hosted Ollama models for local/edge inference (internal gRPC) IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationRun Azure SQL / PostgreSQL
McpConnectorService Expose external MCP tool servers to agents as governed tools (internal gRPC) IntegrationConnectionEstablished, IntegrationRunCompleted IntegrationConnection, IntegrationRun Azure SQL / PostgreSQL
CloudProviderAdapterService Normalise cloud control-plane operations behind one surface POST /integrations/connections IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationRun Azure SQL / PostgreSQL
EmailIntegrationService Send transactional + marketing email (provider-abstracted) (internal) IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationCredential, IntegrationRun Azure SQL / PostgreSQL
SmsIntegrationService Send SMS via Twilio / Israel019 / ACS providers (internal) IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationCredential, IntegrationRun Azure SQL / PostgreSQL
PaymentIntegrationService Integrate payment processors; reconcile commerce callbacks (internal) IntegrationRunCompleted, IntegrationFailed, WebhookDelivered IntegrationConnection, IntegrationCredential, IntegrationRun, IntegrationFailure Azure SQL / PostgreSQL
CrmIntegrationService Integrate CRM systems for business workflows (internal) IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationCredential, IntegrationRun Azure SQL / PostgreSQL
SupportIntegrationService Integrate support/ticketing systems (internal) IntegrationRunCompleted, IntegrationFailed IntegrationConnection, IntegrationCredential, IntegrationRun Azure SQL / PostgreSQL
VendorApiClientRegistryService Catalogue providers and versioned reusable API clients POST /integrations/providers IntegrationProviderRegistered, ExternalApiClientRegistered IntegrationProvider, ExternalApiClient Azure SQL / PostgreSQL
WebhookGatewayService Verify, normalise, dispatch inbound + outbound webhooks POST /webhooks/subscriptions, POST /webhooks/deliveries WebhookSubscribed, WebhookDelivered, IntegrationFailed WebhookSubscription, WebhookDelivery, IntegrationFailure Azure SQL / PostgreSQL + Azure Blob

Implemented

Several services wrap reusable assets that already exist: SmsIntegrationService uses ConnectSoft.Sms.Providers.Twilio / Israel019 / AzureCommunicationServices / Fake; EmailIntegrationService and CrmIntegrationService build on clients such as ConnectSoft.Braze.ApiClient; PaymentIntegrationService builds on ConnectSoft.Bill.ApiClient; CrmIntegrationService/SupportIntegrationService build on ConnectSoft.Deputy.ApiClient; the model services and McpConnectorService use the Azure OpenAI / OpenAI / Ollama integrations and ConnectSoft.Extensions.ModelContextProtocol; OAuth2 vendor auth uses ConnectSoft.Extensions.Http.OAuth2; and analytics dispatch uses ConnectSoft.GoogleAnalytics.MeasurementProtocol and ConnectSoft.Meta.Conversions.

Credential authorization endpoint

The POST /integrations/credentials/rotate endpoint is hosted by VendorApiClientRegistryService as the credential-custody authority and delegates rotation execution to the CredentialRotationWorker, which re-tests against the owning integration service. See APIs and Workers.

Service Interaction

flowchart TB
    AM["Agent Mesh"] -->|"model calls"| OpenAI["OpenAIIntegrationService"]
    AM -->|"model calls"| AzOpenAI["AzureOpenAIIntegrationService"]
    AM -->|"local inference"| Ollama["OllamaIntegrationService"]
    AM -->|"tool calls"| Mcp["McpConnectorService"]

    DG["DevOps & GitOps"] -->|"repo + pipeline ops"| Ado["AzureDevOpsIntegrationService"]
    DG -->|"repo + pipeline ops"| GitHub["GitHubIntegrationService"]

    CP["Control Plane"] -->|"provision"| Cloud["CloudProviderAdapterService"]
    CP -->|"notify"| Email["EmailIntegrationService"]
    CP -->|"notify"| Sms["SmsIntegrationService"]

    Email --> Registry["VendorApiClientRegistryService"]
    Sms --> Registry
    Payment["PaymentIntegrationService"] --> Registry
    Crm["CrmIntegrationService"] --> Registry
    Support["SupportIntegrationService"] --> Registry
    Ado --> Registry
    GitHub --> Registry

    Ext["External Vendors"] -->|"webhooks"| Gateway["WebhookGatewayService"]
    Gateway -->|"normalized events"| Bus[("Azure Service Bus")]
    Payment -->|"reconcile callbacks"| Gateway

    Registry -.credential refs.-> KV[("Azure Key Vault")]
Hold "Alt" / "Option" to enable pan & zoom

Cross-Cutting Service Concerns

  • Persistence — relational aggregates use NHibernate against Azure SQL / PostgreSQL; raw webhook payloads and large request/response bodies go to Azure Blob.
  • Messaging — every service hosts MassTransit consumers and publishes domain/integration events in the canonical envelope; sagas coordinate multi-step delivery and rotation flows.
  • Provider abstraction — communication, model, and cloud services depend on interface-driven adapters resolved from the Vendor Registry, so providers are swappable by configuration.
  • Resilience — outbound calls are wrapped with retry, timeout, rate-limit, and circuit-breaker policies; failures become IntegrationFailure aggregates and dead-letter where unprocessable.
  • Credentials — services request short-lived secret material from ConnectSoft.Extensions.Http.OAuth2 / Key Vault at call time; nothing is persisted in plaintext.
  • Observability — ConnectSoft.Extensions.Observability provides Serilog logs, OTEL traces/metrics, and Application Insights export; traceId propagates from the envelope into every external call span.
  • Multi-tenancy — tenantId scopes every connection, credential reference, run, and rate-limit bucket.