IntegrationHost

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Bounded context	BC-16 Connections
Platform / plane	Integration Platform / Capability & Tools
Deployment granularity	standalone host
Status	target · ConnectSoft.Factory.Integration
Built from	connectsoft-microservice · libraries: connectsoft-extensions-http-oauth2, connectsoft-extensions-saas-abstractions, connectsoft-extensions-saas-asp-net-core, connectsoft-extensions-messaging-model, connectsoft-extensions-messaging-model-orleans, connectsoft-extensions-persistence-model-nhibernate, connectsoft-extensions-rate-limiting, connectsoft-extensions-audit-net, connectsoft-extensions-observability
Decisions	ADR-0012, ADR-0015, ADR-0016, ADR-0017, ADR-0022
Traceability	FR-05 FR-11 FUX-02 NFR-02 NFR-13 NFR-18 XL-10 XL-13

Purpose and responsibilities

IntegrationHost composes IntegrationService (connections, BC-16) and ConnectorRegistryService (connectors, subscriptions, deliveries, BC-17) and loads the connector adapters: the first-party client libraries that already exist (Azure DevOps, GitHub, Deputy, Braze, Bill, Twilio, Israel019, Azure Communication Services, Google Analytics Measurement Protocol, Meta Conversions) and the generic HTTP, OpenAPI and MCP adapters. A vendor is registered, not hand-built: the host turns libraries into governed capabilities behind descriptors. The webhook ingress (GW-06) is a separate conditional host, WebhookGatewayService, so that the public inbound surface stays minimal.

Context and boundaries

flowchart LR
    S["IntegrationHost"]
    ToolExecutorHost["ToolExecutorHost"] -->|grpc| S
    KnowledgeHost["KnowledgeHost"] -->|grpc| S
    StudioBff["StudioBff"] -->|sync-http| S
    WebhookGatewayService["WebhookGatewayService"] -->|event| S
    S -->|grpc| GovernanceHost["GovernanceHost"]
    S -->|grpc| ControlPlaneApi["ControlPlaneApi"]
    S -->|sync-http| ext_azure_devops["ext-azure-devops"]
    S -->|sync-http| ext_github["ext-github"]
    S -->|library| ext_client_libraries["ext-client-libraries"]
    S -->|sync-http| ext_identity_platform["ext-identity-platform"]

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

flowchart LR
    subgraph Host["IntegrationHost (2 to 8 replicas)"]
        direction TB
        Conn["IntegrationService<br/>connections, grants"]
        Cx["ConnectorRegistryService<br/>descriptors, subscriptions, deliveries"]
        Adapters["Adapters: first-party clients, HTTP, OpenAPI, MCP"]
    end
    WH["WebhookGatewayService (GW-06)"] -- "verified deliveries" --> Cx
    TE["ToolExecutorHost"] -- "Resolve, Deliver" --> Host
    KH["KnowledgeHost"] -- "Resolve for sources" --> Conn
    SB["StudioBff"] --> Host
    Host -- "credentials, grant policy" --> GOV["GovernanceHost"]
    Cx --> Adapters --> Vendors["Vendors: Azure DevOps, GitHub, SharePoint, Confluence, SaaS APIs"]
    Host --> SQL["('integration-sql')"]

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

Domain model

None modelled

No aggregates are modelled for this item yet.

No entities modelled.

Entities and value objects

None modelled

No entities or value objects are modelled for this item yet.

Data model and storage

Store	Role	Engine / profile	Tables
Integration store	primary	azure-sql / nhibernate-sqlserver	—
Cache and coordination	cache	redis / azure-cache	—

None modelled

No tables are modelled for this item yet.

APIs

Method	Path	Operation	Scope	Side effects	Idempotency	Gateway	Summary
GET	/integration/health	IntegrationHealth	factory.health.read	read	natural	GW-01	Liveness, readiness and dependency health (store, secret broker, connector adapters, webhook ingress).
GET	/integration/meta/connectors	IntegrationAdapters	factory.meta.read	read	natural	GW-03	Connector adapters loaded in this host (first-party clients and generic HTTP, OpenAPI, MCP) with versions and capability interfaces.

None modelled

No gRPC methods are modelled for this item yet.

Messages

None modelled

No events are modelled for this item yet.

None modelled

No commands are modelled for this item yet.

None modelled

No consumed events are modelled for this item yet.

Workers and jobs

None modelled

No workers are modelled for this item yet.

Actors and grains

None modelled

No grains are modelled for this item yet.

Sagas and long-running flows

None modelled

No sagas are modelled for this item yet.

Options and configuration

Section	Key	Type	Default	Reloadable	Secret	Summary
Integration:Host	EnabledModules	string[]	[connections, connectors]	no	no	Modules composed into this host; webhook ingress is a separate conditional host.
Integration:Adapters	Enabled	string[]	[azure-devops, github, generic-http, openapi, mcp, deputy, braze, bill, twilio, israel019, acs, ga-measurement, meta-conversions]	no	no	First-party client libraries and generic adapters loaded as connector implementations.
OrleansMessaging	ServiceName	string	integration	no	no	Messaging profile service name.

Metrics and observability

Metric	Instrument	Unit	Dimensions	Summary
connectsoft.factory.integration.host.requests	counter	{request}	module, status	Requests per module.
connectsoft.factory.integration.host.adapter_health	gauge	1	adapter	Adapter health.

Security

Authentication	client-credentials
Scopes	factory.health.read (Health probes.); factory.meta.read (Adapter metadata.)
Roles	Operator, PlatformAdmin, Observer
Tenant isolation	row-filter
Data classification	confidential
Max side-effect class	external
Secrets	integration-sql (key-vault, rotate 90 d); messaging-transport (key-vault, rotate 90 d)

Dependencies

Outbound

Target	Kind	Purpose	Failure mode	Required
GovernanceHost	grpc	Secret brokering for connection credentials and policy for grants.	fail-fast	yes
ControlPlaneApi	grpc	Project scope and approvals for external deliveries.	fail-fast	yes
ext-azure-devops	sync-http	Work items, repositories, pipelines.	degrade	no
ext-github	sync-http	Repositories, issues, pull requests.	degrade	no
ext-client-libraries	library	First-party vendor clients behind connector descriptors.	degrade	no
ext-identity-platform	sync-http	Workload identity and caller validation.	fail-fast	yes

Inbound

Target	Kind	Purpose	Failure mode	Required
ToolExecutorHost	grpc	Connections for external tools and consumed MCP servers.	—	yes
KnowledgeHost	grpc	Connections for source ingestion.	—	yes
StudioBff	sync-http	Connection and connector administration.	—	yes
WebhookGatewayService	event	Verified inbound deliveries.	—	yes

Failure and recovery

Scenario	Detection	Recovery	Data impact	RTO (min)
Secret broker unavailable	credential issuance failures	fail closed; no outbound call without a brokered credential	none	15
Vendor outage	adapter health and delivery failures	deliveries retried per connector profile; subscriptions replay after recovery	delayed deliveries	60

NFR targets

Target	Class value (pilot-interactive)	Override
latency_p95_ms	2000	—
availability_pct	99.5	—
throughput_rps	50	—
rpo_minutes	15	—
rto_minutes	240	—
cost_class	low	—

Deployment

Granularity	standalone host
Topologies	saas-default, hybrid, on-prem
Runtime	aks; replicas 2–8
Ports	https 7900, grpc 7902, silo 11900, gateway 30900

Current implementation

The first-party client libraries exist (see the API clients and communication providers library areas); ConnectSoft.Extensions.Http.OAuth2 provides token management. No connection registry, grants, descriptors, subscriptions, deliveries or ingress exist.

Later capabilities

Integration packs as marketplace assets; provider certification suites; vendor cost attribution; secret-expiry forecasting.

Decisions and traceability

Family	Ids
FR	FR-05, FR-11
FUX	FUX-02
NFR	NFR-02, NFR-13, NFR-18
XL	XL-10, XL-13

Related

• Integration overview · IntegrationService · ConnectorRegistryService · WebhookGatewayService

• Integration Platform microservices · bounded contexts · APIs · events · data model

• Services catalog · Ownership map