Notifications and Real time Updates

Notifications & Real-time Updates

This document covers the notification and real-time update system within the Effective Office platform. The system enables automatic synchronization between Google Calendar events and the tablet client application through push notifications and webhook-based event propagation.

For information about the booking workflow that triggers these notifications, see [Room Booking Workflow](Room Booking Workflow). For details about the availability system that responds to these updates, see [Real-time Availability System](Real-time Availability System).

Overview

The notification system consists of three main components: Google Calendar webhook notifications received by the backend, Firebase Cloud Messaging (FCM) for push notifications to mobile clients, and client-side update subscription mechanisms. This architecture ensures that changes made in Google Calendar are immediately reflected on tablet devices without requiring manual refresh or continuous polling.

Notification Architecture

Google Calendar Push Notifications

The backend receives webhook notifications from Google Calendar when events are created, modified, or deleted. The CalendarNotificationsController processes these webhooks and triggers appropriate actions.

Webhook Processing

The notification endpoint at /notifications handles incoming Google Calendar webhooks:

The controller extracts channel information from request headers and fetches recently updated events within a 2-minute window. Events are deduplicated to prevent duplicate notifications.

Subscription Management

The CalendarSubscriptionScheduler automatically manages Google Calendar notification subscriptions, which expire after 7 days. The scheduler runs every 6 days to ensure continuous notification coverage:

Schedule	Frequency	Purpose
Subscription Renewal	Every 6 days	Prevent subscription expiration
Startup Initialization	Application boot	Establish initial subscriptions

The scheduler handles both production and test environment calendars based on configuration.

Firebase Cloud Messaging Integration

The system uses Firebase Cloud Messaging to deliver push notifications to Android tablet clients. The backend sends empty FCM messages that trigger client-side data refresh operations.

Android Client Message Handling

The ServerMessagingService extends FirebaseMessagingService and processes incoming FCM messages:

The service extracts topic information from the message and emits it through a Collector<String> for downstream processing.

Client-side Update Subscription

The tablet client implements a reactive update system that responds to both FCM notifications and internal data changes.

Update Flow Architecture

The ResourceDisposerUseCase manages the subscription lifecycle and applies a 2-second debounce to prevent excessive refresh operations.

Resource Management

The ResourceDisposerUseCase provides proper cleanup mechanisms to prevent memory leaks:

Method	Purpose	Scope
invoke()	Start update subscription	CoroutineScope(Dispatchers.IO + SupervisorJob())
dispose()	Cancel subscriptions and cleanup	Cancels all coroutines in scope

Configuration

The notification system requires several configuration parameters defined in the application configuration:

Calendar Subscription Configuration

calendar:
  subscription:
    default-app-email: ${DEFAULT_APP_EMAIL}
    application-url: ${APPLICATION_URL}
    test-application-url: ${TEST_APPLICATION_URL}
    calendars: ${CALENDARS}
    test-calendars: ${TEST_CALENDARS}
    firebase-credentials: ${FIREBASE_CREDENTIALS}

Required Environment Variables

Variable	Purpose	Example
DEFAULT_APP_EMAIL	Default email for calendar operations	Service account email
APPLICATION_URL	Production webhook URL	https://api.example.com
CALENDARS	Production calendar IDs	Comma-separated list
FIREBASE_CREDENTIALS	FCM service account credentials	Path to JSON file

Error Handling and Reliability

The system implements several reliability mechanisms:

Deduplication

• Event-based deduplication prevents duplicate notifications
• Message number tracking for webhook reliability

Subscription Resilience

• Automatic subscription renewal every 6 days
• Startup initialization ensures subscription establishment
• Separate handling for production and test environments

Client-side Robustness

• Debounced updates prevent UI thrashing
• Coroutine-based resource management with proper cleanup
• Supervision job ensures individual failure isolation