Notification Module Specification¶

Purpose¶

The notification module implements the Notification Domain inside the Spring Boot Modulith. It owns notification requests, recipient resolution, preferences, templates, schedules, reminders, escalations, delivery attempts, read status, provider callbacks, and communication history.

Owned Domain¶

Notification owns communication delivery workflow state. It records source references and message state but does not own tender deadlines, compliance expiry, bid approvals, contract milestones, learning progress, subscription facts, or AI prioritization source facts.

Owned Aggregates¶

Aggregate	Responsibility
Notification Request	Source reference, notification type, requested recipients, priority, and reason.
Notification	Message instance, recipients, rendered template reference, priority, schedule, read status, and lifecycle.
Notification Preference	User or organization channel preferences, quiet hours, frequency, opt-in, and opt-out.
Notification Template	Approved templates by type, channel, language, and version.
Notification Schedule	Immediate, delayed, repeated, and deadline-relative timing rules.
Delivery	Channel delivery attempts, provider responses, retries, and failures.
Escalation	Escalation rules and instances for unread, undelivered, or unacknowledged messages.
Communication History	Append-style record of delivery, read, acknowledgement, dismissal, and escalation events.

Owned Entities¶

Notification Request, Notification, Recipient, Notification Channel, Notification Preference, Notification Template, Notification Schedule, Reminder, Escalation, Delivery Attempt, Communication History Entry, and Read Receipt.

Owned Value Objects¶

NotificationId, NotificationRequestId, NotificationType, NotificationPriority, ChannelType, DeliveryStatus, ReadStatus, EscalationLevel, DeliveryWindow, QuietHours, ScheduleRule, TemplateVersion, SourceReference, RecipientReference, ProviderMessageId, and CommunicationSubject.

Commands¶

Command	Responsibility
RequestNotification	Accept source-domain notification request with source reference.
ResolveRecipients	Resolve users, roles, teams, organizations, or contacts.
CreateNotification	Create message instance and channel plan.
UpdateNotificationPreference	Change channel, timing, or frequency preferences.
ApproveNotificationTemplate	Approve template version for use.
ScheduleNotification	Schedule immediate, delayed, recurring, or deadline-relative delivery.
RenderNotification	Render approved template for channel delivery.
RecordDeliveryAttempt	Record provider send attempt and metadata.
MarkNotificationRead	Record recipient read state.
AcknowledgeNotification	Record required acknowledgement.
DismissNotification	Record recipient dismissal and reason.
EscalateNotification	Create escalation instance after threshold.
RecordCommunicationHistory	Append communication history event.

Queries¶

Query	Responsibility
GetNotificationRequest	Return request source, type, and status.
GetNotificationsForRecipient	Return recipient-visible notification list.
GetNotificationDetails	Return message state, source reference, and delivery summary.
GetNotificationPreferences	Return scoped preference records.
GetNotificationTemplates	Return approved or draft templates where authorized.
GetNotificationSchedules	Return schedules and reminders.
GetDeliveryAttempts	Return provider attempts and statuses.
GetEscalations	Return escalation workflow records.
GetCommunicationHistory	Return auditable communication history.

Application Services¶

NotificationRequestApplicationService, RecipientResolutionApplicationService, NotificationApplicationService, NotificationPreferenceApplicationService, TemplateApplicationService, SchedulingApplicationService, ReminderApplicationService, DeliveryApplicationService, EscalationApplicationService, ProviderCallbackApplicationService, and CommunicationHistoryApplicationService.

Domain Services¶

RecipientResolutionService, ChannelSelectionService, PreferenceApplicationService, PriorityService, TemplateSelectionService, SchedulingService, QuietHoursService, DeliveryRetryService, EscalationService, ConsentAndChannelComplianceService, and CommunicationHistoryService.

Policies¶

Recipient Resolution Policy, Channel Selection Policy, Preference Application Policy, Priority Policy, Template Selection Policy, Scheduling Policy, Quiet Hours Policy, Delivery Retry Policy, Escalation Policy, Communication History Policy, and Consent And Channel Compliance Policy.

Repositories¶

NotificationRequestRepository, NotificationRepository, RecipientRepository, NotificationChannelRepository, NotificationPreferenceRepository, NotificationTemplateRepository, NotificationScheduleRepository, ReminderRepository, DeliveryAttemptRepository, ReadReceiptRepository, EscalationRepository, CommunicationHistoryRepository, ProviderCallbackRepository, and NotificationAuditRepository.

Events Published¶

NotificationRequested, NotificationCreated, NotificationScheduled, NotificationRendered, DeliveryAttempted, NotificationSent, NotificationDelivered, NotificationFailed, NotificationRead, NotificationAcknowledged, NotificationDismissed, NotificationEscalated, NotificationPreferenceUpdated, and CommunicationHistoryRecorded.

Events Consumed¶

TenderDeadlineTracked, BriefingSessionTracked, ComplianceDocumentExpired, ComplianceRiskIdentified, BidTaskAssigned, ApprovalRequested, ContractRiskIdentified, MilestoneUpdated, LearningRecommendationCreated, CertificateIssued, TrialEndingSoon, InvoiceIssued, PaymentFailed, HumanApprovalRequired, and BillingNotificationRequested.

REST API Responsibility¶

The module owns API responsibilities for notification requests, notifications, recipient resolution, preferences, templates, schedules, reminders, delivery attempts, read state, escalation workflows, communication history, and provider callbacks. Final endpoint specs are deferred.

Database Ownership¶

Notification owns conceptual persistence for notification requests, notifications, recipients, channels, preferences, templates, schedules, reminders, delivery attempts, read receipts, escalations, communication history, channel callbacks, and notification audit logs.

Module Dependencies¶

Allowed dependencies are shared kernel identifiers, identity user and authorization context, source-domain events, organization contact references, intelligence timing or priority recommendations, analytics projections, and channel-provider adapters through infrastructure boundaries.

Forbidden Dependencies¶

Notification must not mutate source-domain facts, own source deadlines or approvals, bypass user preferences except through explicit critical policy, store provider secrets in records, or become the authoritative store for business actions.

AIOS Interaction Boundary¶

AIOS may suggest priority, timing, grouping, and summary text. Notification owns final recipient, channel, template, schedule, delivery, and escalation decisions.

Security And Tenant Rules¶

Notification requests must include tenant context where source facts are tenant-scoped.
Recipients must be resolved through authorized references, not copied identity ownership.
Channel delivery must respect consent, preferences, quiet hours, critical override policy, and provider constraints.
Message content must follow classification and retention rules.
Provider callbacks must be validated, deduplicated, and attached to delivery attempts.

Test Strategy¶

Tests must cover request validation, recipient resolution, channel selection, preferences, templates, schedule rules, quiet hours, delivery retries, provider callbacks, read and acknowledgement state, escalation, communication history, event publication, idempotent consumption, tenant filtering, and Spring Modulith boundary verification.

Future Microservice Extraction Notes¶

Notification can be extracted when channel volume and provider integrations increase. Extraction requires stable notification request contracts, source reference rules, provider callback contracts, tenant-aware preference storage, and event delivery for acknowledgement outcomes.

Mermaid Component Diagram¶

flowchart TD
    Api[notification.api.rest]
    App[notification.application.service]
    Command[notification.application.command]
    Query[notification.application.query]
    Domain[notification.domain.model]
    Policy[notification.domain.policy]
    Repo[notification.infrastructure.persistence]
    Integration[notification.infrastructure.integration]
    Messaging[notification.infrastructure.messaging]
    Identity[identity context]
    Sources[source domain events]
    Intelligence[intelligence recommendations]
    Providers[channel providers]
    Analytics[analytics projections]

    Api --> App
    App --> Command
    App --> Query
    App --> Domain
    Domain --> Policy
    App --> Repo
    App --> Integration
    App --> Messaging
    App --> Identity
    App --> Sources
    App --> Intelligence
    Integration --> Providers
    Messaging --> Analytics