Internal Events

Executive Summary

Internal Events defines the logical event model for communication between Spring Boot Modulith modules. Events are domain-owned business facts, not technical notifications or hidden cross-module method calls.

Why This Exists

Algosure needs event-driven coordination across Domains, workflows, AIOS, notifications, analytics, integrations, and future extraction boundaries. A governed internal event model prevents tight coupling and preserves source-domain ownership.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Internal events allow modules to react independently to business changes while keeping ownership, audit, tenant context, and future delivery options clear.

Event Model

flowchart LR
    Aggregate[Aggregate or Domain Service]
    Event[Domain Event]
    Handler[Module Event Handler]
    Projection[Read Model or Projection]
    Workflow[Workflow Reaction]
    AIOS[AIOS Reaction]
    Notification[Notification Reaction]
    Analytics[Analytics Reaction]
    Outbox[Outbox Boundary]

    Aggregate --> Event
    Event --> Handler
    Handler --> Projection
    Handler --> Workflow
    Handler --> AIOS
    Handler --> Notification
    Handler --> Analytics
    Event --> Outbox

Event Ownership Rules

Rule	Meaning
Publisher owns event meaning	The module that publishes the event owns the business meaning and compatibility of that event.
Events are facts	Events describe something that happened in the owning Domain, not a command for another module to obey.
Events include tenant context	Events must carry tenant, actor, correlation, causation, time, and audit metadata where relevant.
Subscribers own reactions	A subscriber owns its own projections, workflow reactions, notifications, analytics, or AIOS triggers.
Events are versioned contracts	Changes that affect subscribers require compatibility review and versioning rules.
Events are not database replication	Events communicate business facts, not raw row changes or hidden table copies.

Candidate Domain Event Families

Publishing Module	Candidate Event Families
Identity	Membership changed, role assigned, permission changed, session risk detected, API key changed.
Organization	Organization onboarded, tenant profile updated, organization user added, organization status changed.
Compliance	Compliance requirement created, evidence uploaded, verification completed, expiry detected, compliance risk raised.
Opportunity	Opportunity discovered, opportunity matched, opportunity saved, opportunity deadline changed, opportunity recommendation created.
Bid	Bid workspace created, bid task assigned, bid document drafted, bid approval requested, bid submission marked ready.
Contract	Contract awarded, milestone created, delivery status changed, invoice recorded, contract closeout completed.
Supplier	Supplier created, quote received, supplier trust changed, supplier performance updated, supplier relationship changed.
Marketplace	Marketplace listing published, supplier need identified, quote request started, marketplace match created.
Funding	Funding need identified, funding readiness changed, funding application submitted, funding offer received, repayment status changed.
Learning	Learning need identified, course started, lesson completed, certificate issued, maturity review completed.
Intelligence	AI task requested, AI recommendation produced, reasoning completed, memory update proposed, AI exception raised.
Notification	Notification requested, notification scheduled, delivery attempted, delivery succeeded, delivery failed.
Analytics	Metric snapshot created, report generated, KPI threshold crossed, executive insight published.
Billing	Subscription created, entitlement changed, invoice issued, payment status changed, subscription cancelled.
Administration	Feature flag changed, platform policy changed, support action recorded, audit review completed.

Outbox Pattern

The outbox pattern is the future-safe delivery mechanism for domain events that need reliable publication outside the local transaction boundary.

sequenceDiagram
    participant App as Application Service
    participant Domain as Domain Model
    participant Store as Module-Owned Persistence
    participant Outbox as Outbox Boundary
    participant Bus as Internal Event Delivery
    participant Subscriber as Subscriber Module

    App->>Domain: Execute command
    Domain-->>App: Produce domain event
    App->>Store: Persist state change
    App->>Outbox: Record event for delivery
    Outbox->>Bus: Deliver event with retry and idempotency
    Bus->>Subscriber: Notify subscribed module
    Subscriber-->>Bus: Process idempotently

Delivery Requirements

Requirement	Meaning
Idempotency	Subscribers must tolerate duplicate events.
Traceability	Events must support correlation, causation, tenant context, actor context, and audit evidence.
Retry safety	Failed delivery must be visible and retryable without corrupting state.
Ordering awareness	Ordering requirements must be explicit when business meaning depends on sequence.
Backward compatibility	Event changes must avoid breaking current subscribers.
Privacy and minimization	Events should carry enough business meaning without exposing unnecessary sensitive data.

Non-Implementation Boundary

This document does not define event class names, payload schemas, broker technology, outbox schema, retry intervals, serialization format, or consumer code.