Real time Availability Workflow

Real-time Availability System

Purpose and Scope

The Real-time Availability System provides live updates of room availability and booking changes across the Effective Office platform. This system ensures that tablet clients receive immediate notifications when rooms become available or unavailable, enabling users to make informed booking decisions with current information.

This document covers the technical implementation of real-time data synchronization, push notifications, and automated refresh mechanisms. For the overall booking workflow, see Room Booking Workflow. For specific booking UI features, see Booking Features.

System Overview

The real-time availability system consists of three primary components that work together to maintain data consistency across all connected clients:

1. Google Calendar Webhook Integration - Receives external calendar change notifications
2. Push Notification System - Distributes update signals to connected clients
3. Timer-based Refresh Logic - Automatically updates availability at event boundaries

Calendar Webhook Integration

The backend receives real-time notifications from Google Calendar through webhook endpoints. When calendar events are modified externally, Google sends HTTP POST requests to the notification endpoint.

Webhook Processing Flow

The CalendarNotificationsController handles incoming webhook requests and processes them as follows:

• Header Validation: Extracts X-Goog-Channel-ID and X-Goog-Resource-State headers
• Channel Lookup: Maps channel ID to calendar ID using ChannelRepository
• Event Fetching: Retrieves recently updated events using GoogleCalendarService
• Deduplication: Prevents duplicate notifications using event ID tracking

Push Notification Distribution

When calendar changes are detected, the system broadcasts update signals to all connected tablet clients using Firebase Cloud Messaging (FCM).

Notification Flow

Component	Method	Purpose
CalendarNotificationsController	receiveNotification()	Webhook entry point
INotificationSender	sendEmptyMessage()	FCM message dispatch
ResourceDisposerUseCase	invoke()	Client-side update subscription
RefreshDataUseCase	invoke()	Data refresh execution

The notification system uses empty FCM messages as triggers rather than sending actual data, ensuring that clients fetch the latest information directly from the API.

Client-Side Update Subscription

The tablet client maintains a persistent subscription to real-time updates through the ResourceDisposerUseCase, which manages background update tasks and resource cleanup.

Update Subscription Architecture

The update subscription implements the following pattern:

• Background Execution: Uses CoroutineScope(Dispatchers.IO + SupervisorJob()) for non-blocking operations
• Debouncing: Applies 2-second debounce to prevent excessive API calls
• Resource Management: Provides dispose() method for proper cleanup

Timer-based Availability Updates

In addition to event-driven updates, the system uses timer-based refresh logic to ensure availability information stays current at event boundaries (when meetings start or end).

Timer Update Logic

The UpdateUseCase calculates optimal refresh intervals based on upcoming room events:

The timer calculation logic follows these rules:

• Next Event Start: Finds earliest upcoming event start time
• Current Event End: Finds earliest current event end time
• Minimum Delay: Uses shorter of the two calculated delays
• Fallback: Defaults to 1-minute intervals when calculations are invalid

Data Refresh Implementation

The RoomRepositoryImpl serves as the data access layer for real-time updates, coordinating between network APIs and local caching mechanisms.

Room Data Retrieval

The repository implements time-rounded data fetching to optimize API usage:

Key implementation details:

• Time Rounding: Rounds current time to nearest 15-minute interval for cache efficiency
• Booking Window: Fetches 14-day booking window from current time
• Meeting Filter: Uses "meeting" tag to filter relevant workspaces

Real-time Update Flow Integration

The complete real-time availability system integrates all components through a coordinated flow that ensures consistent data across all clients.

End-to-End Update Sequence

This integrated approach ensures that:

• Immediate Response: External changes trigger instant notifications
• Efficient Updates: Debouncing prevents API flooding
• Scheduled Consistency: Timers maintain accuracy at event boundaries
• Resource Management: Proper disposal prevents memory leaks