Integration Platform — aggregate roots¶

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

Aggregate	Service	Root entity	Events	Tables
ConnectorDescriptor	ConnectorRegistryService	ConnectorDescriptor	ConnectorActivated, ConnectorDeprecated	ConnectorDescriptors
Subscription	ConnectorRegistryService	Subscription	ConnectorSubscriptionChanged	Subscriptions
Delivery	ConnectorRegistryService	Delivery	DeliveryReceived, DeliveryDispatched, DeliveryFailed, DeliveryReplayed	Deliveries
Connection	IntegrationService	Connection	ConnectionRegistered, ConnectionStateChanged, ConnectionGrantChanged, CredentialRotated	Connections, ConnectionGrants
InboundDelivery	WebhookGatewayService	InboundDelivery	InboundDeliveryVerified, InboundDeliveryRejected	InboundDeliveries

ConnectorDescriptor (ConnectorRegistryService)¶

A provider capability definition — capability interfaces (repositories, work items, pipelines, messaging, email, payments…), versioned client adapter, retry and rate-limit profile, webhook scheme (signature, replay window), configuration form and certification evidence.

Field	Type	Required	Description
`connectorId`	`string`	yes
`version`	`string`	yes
`tenantId`	`string`	yes	Platform tenant for ConnectSoft connectors; tenants may register their own.
`provider`	`string`	yes
`capabilities`	`list:string`	yes	Capability interfaces implemented.
`adapterRef`	`string`	yes	Client library and version (first-party client, generic HTTP, OpenAPI, MCP).
`retryProfile`	`json`	yes
`rateLimitProfile`	`json`	yes
`webhookScheme`	`json`	no	Signature algorithm, header, replay window, deduplication key
`configurationForm`	`string`	yes	Descriptor of the settings a connection of this connector needs.
`certificationRef`	`string`	no	Conformance suite evidence (artifact).
`state`	`enum:ConnectorState`	yes
`releaseId`	`string`	no	Published asset release when distributed as an integration pack.

Invariants

A connector is Active only with certification evidence from the conformance suite; a changed adapter version re-runs certification.
Every capability exposed to agents is also a tool descriptor (BC-08) with a side-effect class; the connector never bypasses the executor.
Webhook schemes define signature verification and a replay window; a connector without a scheme accepts no inbound deliveries.

States (ConnectorState)

stateDiagram-v2
    Draft --> Certified : ConformanceSuitePassed
    Certified --> Active : Activate
    Active --> Deprecated : Deprecate

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

Subscription (ConnectorRegistryService)¶

A tenant's subscription to inbound events of a provider through a connection, with the event types, the target (workflow trigger, knowledge sync, fleet signal) and the verification state.

Field	Type	Required	Description
`subscriptionId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	no
`connectorId`	`string`	yes
`connectionId`	`guid`	yes
`eventTypes`	`list:string`	yes
`target`	`json`	yes	kind: workflow-trigger
`ingressRef`	`string`	yes	GW-06 endpoint identity for this subscription.
`active`	`bool`	yes
`lastDeliveryAt`	`datetime`	no

Invariants

A subscription references an Active connector and an Active connection with a grant for subject kind Source or Tool.
Inbound deliveries are accepted only for the subscription's event types and only after signature and replay verification.

Delivery (ConnectorRegistryService)¶

One inbound or outbound delivery with verification, deduplication, dispatch, acknowledgement, failure and replay history; the receipt is the evidence.

Field	Type	Required	Description
`deliveryId`	`guid`	yes
`tenantId`	`string`	yes
`direction`	`enum:DeliveryDirection`	yes
`connectorId`	`string`	yes
`connectionId`	`guid`	yes
`subscriptionId`	`guid`	no
`externalId`	`string`	yes	Vendor delivery id or idempotency key.
`dedupKey`	`string`	yes
`state`	`enum:DeliveryState`	yes
`payloadRef`	`string`	yes	Artifact reference (payload never in the row).
`payloadHash`	`hash`	yes
`attempts`	`int`	yes
`receiptRef`	`string`	no
`receivedAt`	`datetime`	yes
`settledAt`	`datetime`	no

Invariants

The same dedupKey within the replay window is Deduplicated, never dispatched twice.
An outbound delivery of external class is sent only with the policy decision and approval the calling tool carried; the delivery records them.
Replay after a vendor incident re-dispatches from the stored payload with a new attempt, never by asking the vendor to resend secrets.

States (DeliveryState)

stateDiagram-v2
    Received --> Verified : SignatureAndReplayChecked
    Received --> Rejected : VerificationFailed
    Verified --> Deduplicated : DuplicateWithinWindow
    Verified --> Dispatched : DispatchedToTarget
    Dispatched --> Acknowledged : TargetAcknowledged
    Dispatched --> Failed : TargetFailedAfterRetries
    Failed --> Replayed : OperatorReplay
    Replayed --> Dispatched : Redispatched

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

Connection (IntegrationService)¶

A tenant-scoped connection to one external system with its provider, endpoint policy (hosts, methods, rate limits), credential reference and kind, rotation metadata, grants and health.

Field	Type	Required	Description
`connectionId`	`guid`	yes
`tenantId`	`string`	yes
`name`	`string`	yes
`provider`	`string`	yes	azure-devops
`endpointPolicy`	`json`	yes	Allowed hosts, base URL, methods, rate limits, timeouts
`credentialKind`	`enum:CredentialKind`	yes
`credentialRef`	`string`	yes	Key Vault reference; the Secret Broker resolves it per use.
`rotation`	`json`	yes	lastRotatedAt, rotationDays, nextRotationDue, rotationOwner
`state`	`enum:ConnectionState`	yes
`healthy`	`bool`	yes
`lastVerifiedAt`	`datetime`	no
`version`	`long`	yes

Invariants

A connection stores a credential reference and kind, never a value; verification and every use go through the Secret Broker, which issues a short-lived scoped credential.
A connection is usable only in state Active and healthy and only by subjects with a grant; a project's source scope, an agent's release closure or a tool descriptor must name the connection and hold a grant.
Secrets never appear in prompts, events, receipts or release manifests; receipts record the connection id and credential kind only.
Revocation is immediate and emits an event that stops every dependent source, tool and server.

States (ConnectionState)

stateDiagram-v2
    Draft --> Verified : VerificationSucceeded
    Verified --> Active : Activate
    Active --> Degraded : HealthProbeFailed
    Degraded --> Active : HealthProbeRecovered
    Active --> Suspended : Suspend
    Suspended --> Active : Resume
    Active --> Revoked : Revoke
    Suspended --> Revoked : Revoke
    Degraded --> Revoked : Revoke

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

Entities: Grant · Value objects: —

InboundDelivery (WebhookGatewayService)¶

One inbound HTTP delivery at a subscription's ingress identity — headers hash, signature check, timestamp and replay window, deduplication key, payload capture and the verification outcome.

Field	Type	Required
`inboundId`	`guid`	yes
`tenantId`	`string`	yes
`ingressRef`	`string`	yes
`subscriptionId`	`guid`	no
`connectorId`	`string`	no
`externalId`	`string`	no
`dedupKey`	`string`	no
`signatureValid`	`bool`	yes
`outcome`	`enum:VerificationOutcome`	yes
`payloadRef`	`string`	no
`payloadHash`	`hash`	no
`receivedAt`	`datetime`	yes

Invariants

A delivery is forwarded only when the ingress is known, the signature verifies under the connector's scheme and the timestamp is inside the replay window; everything else is rejected with its outcome and no payload is dispatched.
Payloads are captured by hash to the artifact store and never logged.
The gateway is stateless beyond the deduplication cache; the connector module holds the delivery lifecycle.