Codex Reaktor Notifications Design

1. Where We Are Today

The actual Reaktor framework module is named :reaktor-notification in Gradle. The strategic document and product language often call the product surface reaktor-notifications; this design treats that plural name as the product capability, while preserving the current module name unless the team chooses a rename before publication.

2. What To Take From Expo Notifications

Expo is useful as a product-shape reference because it separates the client library from the push relay service. The client requests permissions, gets a project-scoped push token, receives and responds to notifications, and can schedule local notifications. The service accepts server requests, forwards them to FCM/APNs, and reports tickets and receipts.

3. Requirements And Boundaries

Non-goals

• No visual journey builder in the first release.
• No attempt to hide platform affordances behind a lowest-common-denominator API.
• No foreground-service notification ownership; those belong to media, call, navigation, and long-running work modules.
• No product-specific notification worker in BestBuds once the Reaktor service exists.

4. Alignment With Existing Reaktor Docs

The existing Reaktor docs frame the framework as a composition kernel: graph structure is the runtime source of truth, modules contribute typed capabilities and contracts, visitors interpret the graph, commands mutate it safely, and auth/security policy is part of the runtime context. Notifications should follow that model directly.

Runtime planes

5. Target Architecture

The key design choice is to model notifications as a typed workflow rather than as a push-send helper. A product service creates a NotificationIntent. Reaktor persists it, fans it out to endpoints, applies policy, delivers through a provider, records receipts, and turns client interactions into graph actions.

Product service or graph node
  |
  | NotificationIntent
  v
NotificationsService intake
  |-- idempotency check
  |-- persist NotificationRecord
  |-- publish notifications.fanout.requested
  v
FanoutService
  |-- resolve target to endpoints
  |-- apply quiet hours, category mutes, frequency caps
  |-- publish notifications.delivery.task
  v
DeliveryWorker
  |-- select provider: FCM, APNS_DIRECT, WEB_PUSH, EXPO
  |-- retry/circuit-breaker
  |-- publish notifications.delivery.receipt
  v
ReceiptWorker
  |-- update attempts and receipts
  |-- invalidate dead endpoints
  v
Client NotificationsNode
  |-- received listener
  |-- response listener
  |-- NotificationInteractionEvent -> route or graph action

6. Common Domain Model

Domain classes stay semantic and provider-neutral. FCM, APNs, Web Push, and Expo-specific fields belong in provider translators, not in the product-facing intent.

@Serializable
data class NotificationIntent(
    val tenantId: String,
    val appId: String,
    val type: String,
    val target: NotificationTarget,
    val content: NotificationContent,
    val route: NotificationRoute,
    val priority: NotificationPriority = NotificationPriority.Normal,
    val category: String? = null,
    val scheduledAt: Instant? = null,
    val idempotencyKey: String? = null,
    val correlationId: String? = null,
)

@Serializable
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
}

@Serializable
data class NotificationContent(
    val title: String,
    val subtitle: String? = null,
    val body: String,
    val imageUrl: String? = null,
    val categoryId: String? = null,
    val threadId: String? = null,
    val person: NotificationPerson? = null,
    val badge: Int? = null,
    val sound: NotificationSound = NotificationSound.Default,
    val interruptionLevel: InterruptionLevel = InterruptionLevel.Active,
    val data: Map<String, String> = emptyMap(),
)

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

7. Typed Workflow And Bus Kinds

Every asynchronous hop should be explicit, idempotent, and observable. The notification pipeline uses Reaktor service handlers and bus envelopes rather than ad hoc queues.

8. Operational Data Store

Notification truth is operational truth, not product business truth. D1 is the default for Cloudflare edge deployments; Postgres is the default for Spring-first deployments.

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)
);

9. Module Layout And Source Sets

Keep the module as one KMP package. Platform-specific implementation belongs in source sets; orchestration contracts stay in commonMain.

reaktor-notification/
  src/commonMain/kotlin/dev/shibasis/reaktor/notification/
    domain/               NotificationIntent, Target, Content, Route, Endpoint
    client/               NotificationsClient, Permission, Listeners
    service/              NotificationsService, Orchestrator, Stores
    policy/               DeliveryPolicy, QuietHours, FrequencyCap
    provider/             PushProvider, ProviderErrorClassifier
    graph/                NotificationsNode, GraphNotificationRouteDispatcher
  src/androidMain/
    AndroidNotificationsClient, FcmTokenProvider, AndroidChannelRegistry
    AndroidNotificationRenderer, ReaktorFirebaseMessagingService
  src/iosMain/
    IosNotificationsClient, ApnsRegistrationProvider, AppleCategoryRegistry
    IosNotificationInteractionBridge, CommunicationNotificationBuilder
  src/jsMain/
    DurableObjectIntake, D1NotificationStore, FanoutService, WebPushProvider
  src/jvmMain/
    FirebasePushProvider, ApnsDirectPushProvider, FirebaseDeliveryWorker
    PostgresNotificationStore, ReceiptWorker

First API cut

var Feature.Notifications by CreateSlot<NotificationsClient>()

interface NotificationsClient {
    suspend fun getPermissions(): NotificationPermissionStatus
    suspend fun requestPermissions(options: NotificationPermissionOptions): NotificationPermissionStatus
    suspend fun getDeviceToken(): DevicePushToken?
    suspend fun registerRemoteEndpoint(userId: String?): RegisterEndpointResult
    suspend fun scheduleLocal(request: LocalNotificationRequest): LocalNotificationId
    fun addReceivedListener(listener: suspend (NotificationEnvelope) -> Unit): ListenerHandle
    fun addResponseListener(listener: suspend (NotificationResponseEvent) -> Unit): ListenerHandle
}

enum class NotificationCapabilityLevel {
    Unavailable,
    LocalOnly,
    RemotePush,
    RemotePushWithActions,
    RemotePushWithRichMedia,
}

10. Provider Strategy

Provider support should be explicit. The product-facing intent is stable, while providers translate it into FCM, APNs, Web Push, or Expo-specific requests and classify errors into common retry decisions.

sealed class RetryDecision {
    data class Retryable(val delay: Duration? = null) : RetryDecision()
    data class InvalidateEndpoint(val reason: String) : RetryDecision()
    data object Terminal : RetryDecision()
}

interface ProviderErrorClassifier {
    fun classify(error: Throwable): RetryDecision
}

11. Typed Routing Into The Graph

A notification tap is a graph event, not a deep-link string. The route is serialized into the provider payload and restored into NotificationInteractionEvent when the app receives a tap, action button, direct reply, or foreground response.

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 -> graph.dispatchPath(route.path)
            is NotificationRoute.GraphAction -> {
                val action = ActionRef(route.type, payloadSchema = route.type)
                actionRegistry.dispatch(action, TactileValue.fromJson(route.payloadJson))
            }
            NotificationRoute.None -> Unit
        }
    }
}

12. Policy Engine

Policy runs during fanout before provider delivery. It is a pure function of intent, endpoint, and time so it can be unit tested without Cloudflare, Firebase, APNs, or a device.

interface DeliveryPolicy {
    fun permits(intent: NotificationIntent, endpoint: NotificationEndpoint, now: Instant): PolicyDecision
}

sealed class PolicyDecision {
    data object Send : PolicyDecision()
    data class Suppress(val reason: String) : PolicyDecision()
    data class DelayUntil(val at: Instant, val reason: String) : PolicyDecision()
}

13. Security And Privacy

• Tenant isolation: all records and endpoints carry tenantId and appId; hosted mode should use per-tenant D1 bindings or strict tenant partitioning.
• Credential isolation: FCM service accounts, APNs keys, Expo access tokens, and VAPID keys are tenant secrets, never product payload fields.
• Payload minimization: provider payloads should carry display text plus opaque ids. Sensitive content should be fetched after graph route resolution or decrypted by an iOS service extension where needed.
• Auth integration: hosted APIs require reaktor-auth tenant API keys or service credentials. Product-local embedded mode still verifies user and app context before registering endpoints.
• Service principals: intake, fanout, delivery, receipt polling, and DLQ replay run as service principals with explicit scopes, not as synthetic users.
• E2EE boundary: for MLS-backed conversations, provider payloads should carry opaque conversation/message ids and safe preview policy. The server should not gain a plaintext decrypt path; rich display can be delegated to a platform service extension when the product requires it.
• Replay safety: idempotency keys are required for domain-triggered sends such as chat mentions and payment events.

14. Observability

Notifications should never be a black box. Every accepted intent, fanout decision, provider attempt, receipt, endpoint invalidation, and interaction should emit telemetry with shared correlation ids.

Workbench views

15. Implementation Roadmap

16. References Used

This design was produced from the local Reaktor strategic assessment document, the current repository implementation, the existing reaktorWeb docs, and current official documentation for Expo, Firebase, Android, and Apple notification primitives.

• Graph Kernel Analysis
• Reaktor Graph Visitors Design
• Reaktor Actor Model
• Reaktor Implementation Plan
• Auth Architecture and Redesign
• Security Implementation Plan
• FlexBuffer Binary Serialization
• React x Compose Blueprint
• Expo push notifications setup
• Send notifications with the Expo Push Service
• Expo Notifications SDK
• Expo notification types and behaviors
• Firebase Cloud Messaging message types
• Firebase Cloud Messaging error codes
• Android notification runtime permission
• Android NotificationChannel API reference
• Apple UNUserNotificationCenter
• Apple APNs provider API