Integration Platform Overview

Target Architecture — Final-State Design

This page describes the final-state target architecture of the Integration Platform. Where a capability is already implemented in the codebase it is marked with an Implemented callout; everything else is the designed end state the factory converges to. This is an AI-native software factory platform, not a chatbot.

The Integration Platform is the external tool and vendor integration layer of the ConnectSoft AI Software Factory. It is the single, governed boundary through which every other platform reaches systems the factory does not own: source-control hosts, LLM providers, cloud APIs, email and SMS gateways, payment processors, CRM and support systems, and arbitrary third-party vendor APIs. Inbound, it is the factory's webhook front door — normalising external callbacks into canonical factory events.

Where the Agent Mesh supplies reasoning, the Knowledge Platform supplies grounded memory, and the Control Plane supplies orchestration, the Integration Platform supplies reach with governance. It turns the messy, heterogeneous world of external APIs — each with its own auth model, rate limits, payload shapes, and failure semantics — into a uniform, observable, multi-tenant-isolated set of connections, every call of which is traceable back to a single traceId.

Purpose

The platform exists to make external connectivity safe, reusable, and traceable at multi-tenant scale:

• One governed boundary. No factory service calls a third-party API directly. All outbound traffic flows through an integration service that enforces credentials, tenancy, rate limits, and audit.
• Credentials never leak. Secrets live only in Azure Key Vault. Aggregates store references, never plaintext. Rotation is automated and audited.
• Normalise inbound and outbound. Vendor-specific payloads are translated to and from the canonical event envelope so the rest of the factory speaks one language.
• Reusable integration assets. Vendor API clients, OAuth2 flows, and provider adapters are versioned, catalogued libraries reused across tenants and projects rather than re-implemented per service.
• Resilience by default. Retries, circuit breaking, dead-lettering, and health probing are platform concerns, not per-call afterthoughts.

Role in the AI Software Factory

flowchart LR
    CP["Control Plane"] -->|provision integration| IP["Integration Platform"]
    AM["Agent Mesh"] -->|"model + tool calls"| IP
    DG["DevOps & GitOps"] -->|"repo + pipeline ops"| IP
    IP -->|external APIs| Ext["External Vendors"]
    Ext -->|webhooks| IP
    IP -->|"normalized events"| KP["Knowledge Platform"]
    IP -->|"telemetry + failures"| OBS["Observability & Feedback"]
    GOV["Governance, Security & Compliance"] -->|"credential + access policy"| IP
    IP -->|"integration audits"| GOV

Hold "Alt" / "Option" to enable pan & zoom

The Integration Platform sits at the edge of the factory. Every other platform that needs the outside world routes through it: the Agent Mesh calls model providers and MCP tools; the DevOps & GitOps Platform drives Azure DevOps and GitHub; the Control Plane provisions cloud resources and notifies stakeholders. Each interaction is correlated by the canonical envelope traceId, so a single trace links an agent decision → an external API call → a vendor response → a normalised factory event.

Core Responsibilities

Responsibility	Description
Connection management	Establish, configure, test, and retire integration connections per tenant and provider.
Provider registry	Catalogue supported providers, their capabilities, auth models, and versioned adapters.
Credential custody	Reference and rotate secrets held in Key Vault; never persist plaintext.
Outbound invocation	Execute governed calls to external APIs with retry, rate-limit, and circuit-breaker policies.
Webhook ingress	Receive, verify, normalise, and dispatch inbound webhooks as canonical events.
Webhook egress	Deliver factory events to subscribed external endpoints with signed payloads and retry.
Source-control integration	Drive Azure DevOps and GitHub repo, PR, pipeline, and check operations.
Model-provider integration	Front OpenAI, Azure OpenAI, Ollama, and MCP tool servers for the Agent Mesh.
Cloud-provider adapter	Normalise cloud control-plane operations behind a provider-agnostic surface.
Communication	Send email and SMS through provider-abstracted gateways.
Commerce & business systems	Integrate payment processors, CRM, and support/ticketing systems.
Run & failure tracking	Record every integration run and failure for traceability, replay, and health.

Key Capabilities

• Provider-abstracted clients — communication, model, and cloud calls go through interface-driven adapters, so swapping Twilio for Israel019, or OpenAI for Azure OpenAI, is configuration, not code.
• Webhook gateway pattern — a single hardened ingress verifies signatures, enforces tenancy, deduplicates, and fans out normalised events; a matching egress delivers signed factory events outward with at-least-once semantics.
• OAuth2 client flows — ConnectSoft.Extensions.Http.OAuth2 handles client-credentials and authorization-code token lifecycles for vendor APIs.
• MCP connectivity — ConnectSoft.Extensions.ModelContextProtocol exposes external tool servers to agents as governed, audited tools.
• Automated credential rotation — the CredentialRotationWorker rotates and re-tests secrets on schedule or on demand, emitting CredentialRotated.
• External health monitoring — continuous probing of vendor endpoints feeds health into Observability and gates routing.
• Full traceability — every connection, run, delivery, and failure carries the cross-cutting metadata and is correlated by traceId.

High-Level Component Diagram

flowchart TB
    subgraph Contexts["Bounded Contexts"]
        SCM["Source Control Integration"]
        MODEL["Model Providers"]
        CLOUD["Cloud Provider"]
        COMM["Communication"]
        COMMERCE["Commerce"]
        BIZ["Business Systems"]
        VENDOR["Vendor Registry"]
        HOOKS["Webhooks"]
    end

    subgraph Stores["Persistence"]
        SQL[("Azure SQL / PostgreSQL<br/>connections, runs, failures")]
        KV[("Azure Key Vault<br/>credentials")]
        Blob[("Azure Blob<br/>payloads + bodies")]
        Bus[("Azure Service Bus<br/>events")]
    end

    SCM --> SQL
    MODEL --> SQL
    CLOUD --> SQL
    COMM --> SQL
    COMMERCE --> SQL
    BIZ --> SQL
    VENDOR --> SQL
    HOOKS --> SQL
    HOOKS --> Blob

    SCM -.credentials.-> KV
    MODEL -.credentials.-> KV
    COMM -.credentials.-> KV
    COMMERCE -.credentials.-> KV
    BIZ -.credentials.-> KV

    HOOKS --> Bus
    SCM --> Bus
    MODEL --> Bus

Hold "Alt" / "Option" to enable pan & zoom

Integration with Other Platforms

flowchart LR
    AM["Agent Mesh"] -->|"model + MCP tool calls"| IP["Integration Platform"]
    IP -->|"completions, tool results"| AM
    DG["DevOps & GitOps"] -->|"repo, PR, pipeline ops"| IP
    IP -->|"check + status callbacks"| DG
    CP["Control Plane"] -->|"provision, notify"| IP
    IP -->|"run + failure events"| OBS["Observability & Feedback"]
    KP["Knowledge Platform"] -->|"connection knowledge"| IP
    IP -->|"normalized inbound events"| KP
    GOV["Governance, Security & Compliance"] -->|"credential + access policy"| IP

Hold "Alt" / "Option" to enable pan & zoom

Platform	Integration Platform receives	Integration Platform provides
Agent Mesh	Model completion requests, MCP tool invocations	Governed model access, tool results
DevOps & GitOps	Repo, PR, pipeline, and check operations	Source-control execution, status callbacks
Control Plane	Provisioning and notification commands	Run status, failure escalation
Knowledge Platform	Connection and provider knowledge	Normalised inbound external events
Observability & Feedback	—	Integration runs, failures, external health
Governance, Security & Compliance	Credential and access policies	Integration access decisions and audits

Implemented Foundations

Implemented

Substantial integration capability already exists in the codebase and grounds this platform's final-state design:

• Vendor API clients — ConnectSoft.Deputy.ApiClient, ConnectSoft.Braze.ApiClient, ConnectSoft.Bill.ApiClient.
• SMS providers — ConnectSoft.Sms.Providers.Twilio, ConnectSoft.Sms.Providers.Israel019, ConnectSoft.Sms.Providers.AzureCommunicationServices, and ConnectSoft.Sms.Providers.Fake (testing).
• OAuth2 client flows — ConnectSoft.Extensions.Http.OAuth2.
• Model Context Protocol — ConnectSoft.Extensions.ModelContextProtocol (MCP).
• Analytics & conversions — ConnectSoft.GoogleAnalytics.MeasurementProtocol, ConnectSoft.Meta.Conversions.
• LLM providers — Azure OpenAI, OpenAI, and Ollama integrations; source control — Azure DevOps and GitHub integrations.

The final-state platform composes these proven clients and extensions into the full microservice, worker, and webhook-gateway topology described across this section.

Final-State Summary

The Integration Platform is the governed external-connectivity edge of the AI Software Factory. In its final state it comprises 14 microservices, 5 background workers, 8 aggregate roots, and 7 public APIs organised into eight bounded contexts (Source Control, Model Providers, Cloud Provider, Communication, Commerce, Business Systems, Vendor Registry, Webhooks), built on .NET 10, MassTransit on Azure Service Bus, NHibernate over Azure SQL / PostgreSQL, with Azure Key Vault for all credentials and Pulumi for infrastructure. It transforms a sprawl of heterogeneous vendor APIs into a single traceable, reusable, multi-tenant-isolated integration fabric where every external call and inbound webhook is correlated, governed, and observable.

Related Pages

• Bounded Contexts
• Microservices
• APIs
• Workers
• Events
• Aggregate Roots
• Security
• Event Envelope
• Naming Conventions