Integration Containers

Executive Summary

Integration Containers defines the logical containers that mediate Algosure's external relationships: integration gateway, notification service and channel adapters, payment provider integration, AI provider gateway, and external systems.

Why This Exists

Algosure depends on tender sources, compliance authorities, productivity tools, messaging channels, payment services, funding partners, marketplace providers, AI providers, and future country-specific integrations. Integration responsibilities must be explicit so external dependencies do not leak into Domain modules or weaken tenant isolation.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Clear integration containers reduce coupling, make external contracts easier to govern, protect source-domain ownership, and support secure, auditable, event-driven external interaction.

Integration Container View

flowchart LR
    Backend[Spring Boot Modulith Backend]
    Events[Event Layer]

    Integration[Integration Gateway]
    Notify[Notification Service and Channel Adapters]
    Payment[Payment Provider Integration]
    AIGateway[AI Provider Gateway]

    Tender[Public and Private Tender Sources]
    Authorities[SARS, CIPC, CSD, CIDB, COIDA, B-BBEE Agencies]
    Productivity[Gmail, Outlook, Google Drive, OneDrive, DocuSign, WhatsApp]
    Funding[Funding Partners]
    Marketplaces[Marketplace Providers]
    PaymentProvider[External Payment Provider]
    AIProviders[External AI Providers]
    Future[Future Government and Country-Specific Integrations]

    Backend --> Events
    Backend --> Integration
    Backend --> Notify
    Backend --> Payment
    Backend --> AIGateway
    Integration <--> Tender
    Integration <--> Authorities
    Integration <--> Productivity
    Integration <--> Funding
    Integration <--> Marketplaces
    Integration <--> Future
    Notify <--> Productivity
    Payment <--> PaymentProvider
    AIGateway <--> AIProviders
    Integration --> Events
    Notify --> Events
    Payment --> Events

Integration Container Responsibilities

Container	Logical Responsibility
Integration gateway	Provides governed mediation for external tender, government, compliance, productivity, funding, marketplace, and future country-specific integrations.
Notification service and channel adapters	Translates notification intent into approved channel delivery through email, messaging, and future notification channels.
Payment provider integration	Mediates billing and payment-provider interaction, payment status, refunds, disputes, subscription events, and commercial transaction evidence.
AI provider gateway	Mediates external AI provider usage for AIOS while preserving tenant context, policy, safety, provider abstraction, and audit.
External systems	Systems outside Algosure that retain authority over their own data, policies, availability, delivery, commercial terms, and operations.

External System Groups

External Group	Examples	Integration Meaning
Tender sources	Public tender sources, private tender sources	Opportunity discovery, tender documents, amendments, deadlines, awards, clarifications, and source evidence.
Government and compliance authorities	SARS, CIPC, CSD, CIDB, COIDA, B-BBEE agencies	Verification context, registration status, compliance evidence, certificate status, and authority records where authorized.
Productivity and collaboration systems	Gmail, Outlook, Google Drive, OneDrive, DocuSign, WhatsApp	Communication, storage, document retrieval, signature, messaging, and evidence capture where authorized.
Commercial partners	Payment provider, funding partners, marketplace providers	Payments, funding applications, funding status, supplier discovery, quote exchange, marketplace updates, and commercial events.
AI providers	External model and AI capability providers	Model execution behind AIOS governance and provider gateway controls.
Future government and country-specific integrations	Future tax bodies, procurement portals, company registries, identity services, compliance authorities	Jurisdiction-specific expansion without changing core Domain ownership.

Integration Boundary Rules

Rule	Meaning
Integrations are not domain owners	External interactions must be interpreted by the owning Domain or approved application service.
External calls are tenant-scoped	Requests, credentials, consent, evidence, responses, and errors must carry tenant context and authorization.
Contracts are explicit	Each integration needs a governed contract before implementation, including ownership, error handling, retries, idempotency, privacy, and audit.
Events carry business meaning	Integration observations that affect Algosure should become domain-owned business events where appropriate.
Notification delivery is not business completion	Channel delivery status can inform workflows, but the owning Domain or workflow determines business state.
Payment provider controls settlement	Algosure may record payment state and events, but the external provider controls processing, settlement, refunds, and disputes.
Future integrations must not fracture the core	Country-specific systems must extend the integration model without duplicating Domains or bypassing core governance.

Event-Driven Integration Flow

sequenceDiagram
    participant Domain as Owning Domain
    participant Gateway as Integration Gateway
    participant External as External System
    participant Events as Event Layer
    participant Workflow as Workflow Layer

    Domain->>Gateway: Request external interaction with tenant and purpose
    Gateway->>External: Execute governed external interaction
    External-->>Gateway: Return response or status
    Gateway-->>Domain: Return normalized external result
    Domain->>Events: Publish domain-owned business event
    Events->>Workflow: Advance workflow, notification, AIOS, or analytics where subscribed

Non-Implementation Boundary

This document does not define:

• Provider-specific APIs.
• OAuth scopes.
• Credential storage.
• Webhook endpoints.
• Message broker product.
• Retry intervals.
• Channel templates.
• Payment processor selection.
• Country rollout order.