The full-stack notification runtime, from domain intent to graph action

00Where we are today

The reaktor-notification module currently exists as a thin shared seam. It declares all five target source sets in its Gradle build but ships a single abstract class. Everything in this document is forward-looking; nothing below is implemented yet.

What ships today

NotificationAdapter.kt (entire current source)

package dev.shibasis.reaktor.notification

import dev.shibasis.reaktor.core.framework.Adapter

abstract class NotificationAdapter<Controller>(
    controller: Controller
): Adapter<Controller>(controller) {

}

What is not built yet

Effectively the entire module is greenfield. The rest of this document specifies what to build, how it fits the rest of Reaktor, and the order in which to ship it.

01Why notifications are hard

Notifications look simple from the product surface but are one of the most cross-cutting subsystems in modern apps. Nine concerns must be solved in concert; ignoring any one of them produces a system that works in demos and rots in production.

The question is not whether all nine get solved — every production app solves them, somewhere — but where each one is solved: in app code, in the notification module, in the delivery provider, or in an engagement platform. reaktor-notifications takes positions on every layer.

02Inspiration: expo-notifications & Expo Push Service

Expo provides two layers that, taken together, are the benchmark every cross-platform notification library is compared against: expo-notifications (the client library) and Expo Push Service (the hosted delivery API). Understanding both is essential because Reaktor is positioned as the Expo-Push-plus-engagement-platform equivalent for KMP apps.

expo-notifications — the library

A React Native package with a unified API across Android and iOS for the things app code actually needs to do:

Expo Push Service — the delivery primitive

The server POSTs an array of messages (each with to: ExpoPushToken[], title, body, data, sound, badge, …) to exp.host/--/api/v2/push/send. Expo translates to FCM or APNs internally, returns tickets immediately, and exposes a separate endpoint for eventually-consistent receipts (~15 min later).

Where Expo stops

Expo Push is a delivery primitive, not an engagement platform. It does not target by attribute/cohort/behavior, does not schedule campaigns with conditions, does not A/B test, does not personalize per recipient, does not provide open or conversion analytics, does not cap frequency across campaigns, does not respect quiet hours, and does not coordinate with email or SMS.

03Positioning & design philosophy

Six design commitments

04Seven non-negotiables

05The six runtime planes & four graphs

Reaktor describes every module's responsibilities along six canonical runtime planes (per graph-kernel-analysis §Canonical runtime planes). Planes describe ownership, not dependencies. A healthy module knows which plane each of its concerns belongs to and resists the urge to mix them. reaktor-notifications touches all six.

Four graphs (kernel canon · Example 9)

graph-kernel-analysis Example 9 ("Notification and Campaign System") defines the canonical four-graph decomposition. reaktor-notifications implements exactly these graphs; each is independently deployable to a different target.

Facets in play

Facets ("typed meaning attached to a node, port, or edge without subclass explosion" — per graph-kernel-analysis §Build next #2) are how the notification module participates in the rest of the kernel without hardcoded coupling.

06The notification as a typed workflow

A notification is not a "send-push" call — it is a workflow that begins with a domain intent inside a service and ends with a typed graph action on the user's device. Every async hop is a bus kind. Every step is idempotent. Every failure is observable.

End-to-end flow

07Module layout

Each file is a single concern. No god-objects. The platform source sets do not hide platform primitives — they expose them as typed, composable building blocks.

08Domain model (commonMain)

Semantic, provider-neutral. No FCM types. No APNs types. No platform types. All nine types live in commonMain/domain/.

Reference shapes

data class NotificationIntent(
  val tenantId: String,
  val appId: String,
  val type: String,                // "chat.message" | "event.invite"
  val target: NotificationTarget,
  val content: NotificationContent,
  val route: NotificationRoute,
  val priority: NotificationPriority = NotificationPriority.Normal,
  val category: String? = null,    // user-preference category
  val scheduledAt: Instant? = null,
  val idempotencyKey: String? = null,
  val correlationId: String? = null,
)

sealed class NotificationTarget {
  data class User(val userId: String) : NotificationTarget()
  data class Users(val userIds: List<String>) : NotificationTarget()
  data class Installation(val installationId: String) : NotificationTarget()
  data class Installations(val installationIds: List<String>) : NotificationTarget()
  data class Segment(val segmentId: String) : NotificationTarget()   // Phase 2
  data class Topic(val topic: String) : NotificationTarget()           // Phase 2
}

data class NotificationContent(
  val title: String,
  val subtitle: String? = null,        // iOS only
  val body: String,
  val imageUrl: String? = null,
  val categoryId: String? = null,      // iOS category / Android channel action set
  val threadId: String? = null,        // iOS threadIdentifier / Android conversation id
  val person: NotificationPerson? = null,  // communication notifications
  val badge: Int? = null,
  val sound: NotificationSound = NotificationSound.Default,
  val interruptionLevel: InterruptionLevel = InterruptionLevel.Active,
  val data: Map<String, String> = emptyMap(),
)

sealed class NotificationRoute {
  data class OpenPath(val path: String) : NotificationRoute()
  data class GraphAction(val type: String, val payloadJson: String) : NotificationRoute()
  data object None : NotificationRoute()
}

enum class InterruptionLevel { Passive, Active, TimeSensitive, Critical }
enum class NotificationPriority { Low, Normal, High, Urgent }

09Service contracts

Six interfaces in commonMain/service/, each a small concern. The interface boundary is identical across embedded and hosted deployment shapes.

interface NotificationsService {
  suspend fun registerEndpoint(cmd: RegisterEndpointCommand): RegisterEndpointResult
  suspend fun unregisterEndpoint(cmd: UnregisterEndpointCommand)
  suspend fun updatePreferences(cmd: UpdatePreferencesCommand)
  suspend fun createNotification(intent: NotificationIntent): NotificationAccepted
  suspend fun getNotification(id: String): NotificationRecord?
  suspend fun recordInteraction(event: NotificationInteractionEvent)
}

interface NotificationOrchestrator {
  suspend fun accept(intent: NotificationIntent): NotificationAccepted
  suspend fun fanOut(notificationId: String)
  suspend fun deliver(task: DeliveryTask): DeliveryResult
  suspend fun handleReceipt(receipt: ProviderReceipt)
}

interface NotificationEndpointStore {
  suspend fun upsert(endpoint: NotificationEndpoint)
  suspend fun findByUser(tenantId: String, appId: String, userId: String): List<NotificationEndpoint>
  suspend fun findByInstallation(tenantId: String, appId: String, installationId: String): NotificationEndpoint?
  suspend fun markInvalid(endpointId: String, reason: String)
  suspend fun updatePreferences(endpointId: String, prefs: PerCategoryPreferences)
}

interface NotificationStore {
  suspend fun insert(record: NotificationRecord)
  suspend fun updateStatus(id: String, status: NotificationStatus)
  suspend fun appendAttempt(attempt: DeliveryAttempt)
  suspend fun recordReceipt(receipt: ProviderReceipt)
  suspend fun recordInteraction(event: NotificationInteractionEvent)
}

interface PushProvider {
  val kind: PushProviderKind
  suspend fun send(batch: ProviderBatch): ProviderBatchResult
}

interface NotificationRouteDispatcher {
  suspend fun dispatch(event: NotificationInteractionEvent)
}

10Operational data store

D1 (Cloudflare) or Postgres (Spring). Six tables in Phase 1; campaign tables land in Phase 2 if scheduled.

Schema (D1)

CREATE TABLE notification_endpoints (
  id TEXT PRIMARY KEY,
  tenant_id TEXT NOT NULL,
  app_id TEXT NOT NULL,
  user_id TEXT,
  installation_id TEXT NOT NULL,
  platform TEXT NOT NULL,
  provider TEXT NOT NULL,
  token TEXT NOT NULL,
  environment TEXT NOT NULL,
  locale TEXT,
  timezone TEXT,
  device_info_json TEXT NOT NULL,
  preferences_json TEXT NOT NULL,
  status TEXT NOT NULL,
  last_seen_at INTEGER NOT NULL,
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL,
  UNIQUE(tenant_id, app_id, installation_id, provider)
);
CREATE INDEX idx_endpoints_user ON notification_endpoints(tenant_id, app_id, user_id);
CREATE INDEX idx_endpoints_status ON notification_endpoints(tenant_id, status);

CREATE TABLE notification_records (
  id TEXT PRIMARY KEY,
  tenant_id TEXT NOT NULL,
  app_id TEXT NOT NULL,
  type TEXT NOT NULL,
  correlation_id TEXT,
  target_type TEXT NOT NULL,
  target_value TEXT NOT NULL,
  content_json TEXT NOT NULL,
  route_json TEXT NOT NULL,
  category TEXT,
  priority TEXT NOT NULL,
  status TEXT NOT NULL,
  created_at INTEGER NOT NULL,
  scheduled_at INTEGER,
  sent_at INTEGER,
  completed_at INTEGER
);

-- + notification_attempts, notification_receipts,
--   notification_idempotency, notification_interactions

11Android source set

Translates commonMain contracts to Android primitives. Every Android-specific concept the OS exposes is available as a typed building block; nothing is hidden behind a lowest-common-denominator abstraction.

Platform primitives covered

12iOS source set

Wraps UNUserNotificationCenter and APNs registration. Communication-notification & Live-Activity helpers expose iOS-specific features without leaking UNMutableNotificationContent into common code.

Platform primitives covered

13Web push source set P2

Web push is protocol-standardized (not vendor-proprietary) and end-to-end encrypted (AES128-GCM). It requires a Service Worker registration on the page side and a VAPID JWT on the server side. Targeted for Phase 2.

• VAPID — server generates an EC keypair, public key registered with the browser at subscription, server signs each push with the private key.
• Service Worker — receives push events even when the page is closed, displays via registration.showNotification.
• Encryption — payload encrypted with subscriber's public key; decrypted in-browser.

Module pieces: WebPushProvider.kt on the server and a small service-worker.js template on the client. Web push is the most secure provider by default but the least feature-rich (no native action buttons with inline reply, limited styling).

14jsMain: intake & fanout

The Cloudflare-side runtime. A Durable Object is the intake surface; a Worker hosts the fanout ServiceNode; D1 holds the operational store.

Intake from a Durable Object

The DO calls NotificationsService.createNotificationInTransaction(txn, intent) inside the same SQLite transaction that persists the domain event. The call writes both the NotificationRecord and an outbox row atomically; the outbox relay publishes the bus kind asynchronously.

class ChatRoomDurableObject(
  private val db: DurableObjectDatabase,
  private val notifications: NotificationsService
) {
  suspend fun onMessageCreated(message: ChatMessage) {
    db.transaction { txn ->
      persistMessage(txn, message)
      message.mentions.forEach { userId ->
        notifications.createNotificationInTransaction(
          txn,
          NotificationIntent(
            tenantId = tenant,
            appId = "bestbuds",
            type = "chat.mention",
            target = NotificationTarget.User(userId),
            content = NotificationContent(
              title = "${message.author.name} mentioned you",
              body = message.text.take(100),
              threadId = message.roomId,
              person = NotificationPerson(
                id = message.author.id,
                displayName = message.author.name,
                avatarUrl = message.author.avatarUrl,
              ),
            ),
            route = NotificationRoute.GraphAction(
              type = "bestbuds.chat.open",
              payloadJson = """{"chatId":"${message.roomId}"}""",
            ),
            category = "messages",
            idempotencyKey = "mention:${message.id}:${userId}",
            correlationId = message.id,
          )
        )
      }
    }
  }
}

Fanout worker

A ServiceNode consumes notifications.fanout.requested, resolves target → endpoints, applies policy, and publishes one notifications.delivery.task per surviving endpoint. DeliveryPolicy is a pure function of (intent, endpoint, now) and is unit-testable without infrastructure.

class NotificationFanoutService(
  private val records: NotificationStore,
  private val endpoints: NotificationEndpointStore,
  private val policy: DeliveryPolicy,
  private val bus: ReaktorBus,
) : Service() {
  val fanout = PostHandler<FanoutRequest, FanoutResult>(
    ServiceEndpoint.pubSub("notifications.fanout.requested").operation
  ) { request ->
    val record = records.get(request.notificationId)
      ?: return@PostHandler FanoutResult.NotFound

    val targetEndpoints = resolveTarget(record.intent.target, record.tenantId, record.appId)

    val filtered = targetEndpoints.filter { endpoint ->
      endpoint.status == EndpointStatus.Active &&
        policy.permits(record.intent, endpoint, Clock.System.now())
    }

    filtered.forEach { endpoint ->
      bus.publish(
        kind = "notifications.delivery.task",
        payload = DeliveryTask(
          notificationId = record.id,
          endpointId = endpoint.id,
          attemptNumber = 1,
          deadline = Clock.System.now() + 24.hours,
        ),
        serializer = DeliveryTask.serializer(),
        correlationId = record.correlationId,
        causationId = request.messageId,
      )
    }
    FanoutResult.Accepted(filtered.size)
  }
}

15jvmMain: delivery workers

JVM owns provider delivery because the Firebase Admin SDK and APNs HTTP/2 client are mature on JVM and not on JS. Workers consume notifications.delivery.task via reaktor-bus streaming pull, build the provider message, send through Arrow retry + circuit breaker, classify errors, and emit receipts.

class FirebaseDeliveryWorker(
  private val firebase: FirebaseMessaging,
  private val endpoints: NotificationEndpointStore,
  private val records: NotificationStore,
  private val classifier: ProviderErrorClassifier,
  private val bus: ReaktorBus,
) : Service() {

  private val retrySchedule = Schedule
    .exponential<Throwable>(base = 1.seconds)
    .jittered()
    .doWhile { err -> classifier.classify(err) is RetryDecision.Retryable }
    .maxN(10)

  private val breaker = CircuitBreaker(
    maxFailures = 5,
    resetTimeout = 30.seconds,
    openingStrategy = OpeningStrategy.Count,
  )

  val deliver = PostHandler<DeliveryTask, DeliveryResult>(
    ServiceEndpoint.pubSub("notifications.delivery.task").operation
  ) { task ->
    val endpoint = endpoints.findById(task.endpointId)
      ?: return@PostHandler DeliveryResult.EndpointMissing
    val record = records.get(task.notificationId)
      ?: return@PostHandler DeliveryResult.RecordMissing

    val message = MessageBuilder.forEndpoint(endpoint, record.intent.content, record.intent.route)

    val outcome = retrySchedule.retry {
      breaker.protectOrThrow {
        firebase.send(message)
        DeliveryResult.Accepted(firebaseMessageId = message.messageId)
      }
    }

    outcome.fold(
      ifLeft  = { err     -> handleFailure(task, endpoint, err) },
      ifRight = { accepted ->
        bus.publish(
          kind = "notifications.delivery.receipt",
          payload = ProviderReceipt(
            notificationId = task.notificationId,
            endpointId = task.endpointId,
            providerMessageId = accepted.firebaseMessageId,
            result = ProviderResult.Accepted,
            receivedAt = Clock.System.now(),
          ),
          serializer = ProviderReceipt.serializer(),
        )
        accepted
      }
    )
  }

  private suspend fun handleFailure(task: DeliveryTask, endpoint: NotificationEndpoint, err: Throwable): DeliveryResult =
    when (val decision = classifier.classify(err)) {
      is RetryDecision.InvalidateEndpoint -> {
        endpoints.markInvalid(task.endpointId, decision.reason)
        DeliveryResult.EndpointInvalid(decision.reason)
      }
      is RetryDecision.Terminal  -> DeliveryResult.Failed(err)
      is RetryDecision.Retryable -> DeliveryResult.Failed(err) // retries exhausted
    }
}

Receipt worker

class ReceiptWorker(
  private val endpoints: NotificationEndpointStore,
  private val records: NotificationStore,
) : Service() {
  val handle = PostHandler<ProviderReceipt, Unit>(
    ServiceEndpoint.pubSub("notifications.delivery.receipt").operation
  ) { receipt ->
    records.recordReceipt(receipt)
    if (receipt.result is ProviderResult.EndpointInvalid) {
      endpoints.markInvalid(receipt.endpointId, receipt.result.reason)
    }
  }
}

For Expo Push (if used as a provider), an additional worker polls Expo's tickets endpoint after the 15-minute propagation window and updates endpoint state.

16Retry classification

ProviderErrorClassifier maps provider errors to a three-way RetryDecision: InvalidateEndpoint (dead token — remove from store), Retryable (transient — Arrow retries with backoff), Terminal (operator-fixable or unknown — surface to DLQ). One implementation per provider, each tested against fixture error responses captured from real deployments.

17Typed routing into the graph

Tap and action events are not strings. They become NotificationInteractionEvent on the client, and the GraphNotificationRouteDispatcher converts them to typed graph actions or route pushes.

class GraphNotificationRouteDispatcher(
  private val graph: Graph,
  private val actionRegistry: TactileActionRegistry,
) : NotificationRouteDispatcher {

  override suspend fun dispatch(event: NotificationInteractionEvent) {
    when (val route = event.route) {
      is NotificationRoute.OpenPath -> {
        val routeNode = graph.resolveRoute(route.path) ?: return
        graph.dispatch(Push(routeNode.edge(), routeNode.parsePayload(route.path)))
      }
      is NotificationRoute.GraphAction -> {
        val actionRef = ActionRef(route.type, payloadSchema = route.type)
        val payload = TactileValue.fromJson(route.payloadJson)
        actionRegistry.dispatch(actionRef, payload)
      }
      NotificationRoute.None -> Unit
    }
  }
}

18NotificationsNode: graph integration

Notifications live in the graph as a node, not as a parallel system. Lifecycle hooks and DI scope flow naturally from BasicNode.

class NotificationsNode(
  graph: Graph,
  private val client: NotificationsClient,
  private val dispatcher: NotificationRouteDispatcher,
) : BasicNode(graph) {

  override suspend fun onAttach() {
    client.addReceivedListener { envelope ->
      // foreground presentation, badge update, analytics
    }
    client.addResponseListener { response ->
      dispatcher.dispatch(response.toInteractionEvent())
    }
  }

  suspend fun register(userId: String?) {
    val permission = client.getPermissions()
    if (permission == NotificationPermissionStatus.Denied) return
    if (permission == NotificationPermissionStatus.Undetermined) {
      val granted = client.requestPermissions()
      if (granted == NotificationPermissionStatus.Denied) return
    }
    client.registerRemoteEndpoint(userId)
  }
}

fun Graph.NotificationsNode(
  client: NotificationsClient,
  dispatcher: NotificationRouteDispatcher,
): NotificationsNode {
  val node = NotificationsNode(this, client, dispatcher)
  attach(node)
  return node
}

// Installed in the app's root graph:
rootGraph.NotificationsNode(
  client = platformNotificationsClient,
  dispatcher = GraphNotificationRouteDispatcher(rootGraph, actionRegistry),
)

From the developer's perspective notifications are a graph capability. From the runtime's perspective they are a node with lifecycle hooks and DI scope.

19Observability

Every intent, attempt, receipt, and interaction is traced end to end via reaktor-telemetry with a stable notification.correlationId spanning the entire flow.

Standard telemetry attributes

Reaktor Desktop dashboard panels

• Notification flow graph: intake → fanout → delivery → interaction with live counters.
• Endpoint health per tenant, platform, and provider.
• Delivery success rate rolled up by notification type.
• Retry frequency and DLQ depth.
• Interaction conversion: notification → tap → graph action.
• Slow-delivery alerts: P95 delivery latency breaching threshold.

20Hosted vs embedded

Migration from embedded to hosted (or back) is a deployment-config change. Application code does not change.

21Phase 1 / Phase 2 roadmap

22Integration with the rest of Reaktor

Composes through standard Reaktor surfaces. No bespoke wiring. The status column reflects the dependency's own state today — most are partial or aspirational, which is the most important fact this whole document needs to communicate honestly. reaktor-notifications cannot ship faster than the slowest of its dependencies, so Phase 1 sequencing has to follow them.

23Gap analysis & next steps

The honest picture: every concern in this document, except the empty NotificationAdapter class, is not yet implemented. The work below is roughly ordered to unblock the next concern after it lands.

Critical-path recommendation