Skip to content

Integration Engine

Status: Draft for review

Purpose

Own reusable adapters, connection configuration and credential references for external systems that are not primarily advertising channels: email, social login, maps/geocoding, CAPTCHA, calendar/iCal, analytics, payment adapter infrastructure, webhooks and future third-party services.

Owns

  • Integration catalog and provider adapter interfaces
  • Tenant integration instances/configuration
  • Secret references
  • OAuth connection handshakes where applicable
  • Email/SMS/notification delivery adapters
  • Maps/geocoding adapters
  • CAPTCHA verification adapter
  • iCal import/export/sync adapter
  • analytics/tag configuration abstractions
  • outbound webhook subscriptions/delivery

Non-goals

It does not own domain business state, campaigns, financial transactions, or page content.

API contract — functional surface

These are contract-level resources and operations, not final controller/file names.

Method Route Primary actor Contract intent
GET /api/tenant/v1/integrations/catalog Tenant Admin List integrations available under entitlement.
POST /api/tenant/v1/integrations Tenant Admin Create/configure integration instance.
PATCH /api/tenant/v1/integrations/{id} Tenant Admin Update non-secret configuration/status.
POST /api/tenant/v1/integrations/{id}/test Tenant Admin Run safe connectivity/configuration check.
POST /api/tenant/v1/webhook-subscriptions Tenant Admin/Custom Client Register outbound webhook subject to scope.
GET /api/public/v1/calendar/{offeringId}.ics Visitor/Authorized Consumer Export permitted calendar feed.
POST /api/tenant/v1/calendars/imports Business Manager Configure/import external iCal source.

All mutating operations apply the global tenant, authorization, audit and idempotency rules where relevant.

Events

  • integration.connected
  • integration.failed
  • webhook.delivery_failed
  • calendar.imported
  • calendar.sync_failed
  • message.delivered
  • message.delivery_failed

Roles & responsibility matrix

Legend: A accountable, R responsible, C consulted, I informed, — none.

Capability Platform Admin Tenant Owner Tenant Admin Specialist/Manager Customer/Visitor
Integration catalog/provider adapters A/R I I C —
Tenant integration setup I A R C —
Operational integration use I I C R I
Secrets rotation C A R C —

Dependencies

  • Platform Engine for tenant/entitlement scope
  • Operations Engine for job/retry/monitoring
  • Domain engines as adapter consumers
  • Channel Engine for advertising-specific providers

Internationalization Contract

  • Own/provider-adapt machine-translation integrations and localized communication provider capabilities, but not canonical translation state.
  • Provider credentials remain tenant-isolated.
  • Machine-assisted translation must preserve source locale, target locale, provider metadata and must not silently replace approved human translations.

Security / isolation requirements

  • Secrets use a dedicated secret store/reference.
  • Inbound webhooks verify authenticity.
  • Outbound webhooks are signed, scoped and retryable.
  • Integration tests never reveal secrets.

Acceptance criteria

  • Legacy SMTP, Mapbox, reCAPTCHA, social login and iCal capabilities have target adapters.
  • Integrations can be enabled per tenant without branching core domain code.
  • Custom-plan clients can subscribe to approved webhooks.