Offline Mode

The platform handles connectivity loss differently for each frontend. The PWA implements a full offline-first architecture, while Telegram operates as a purely online channel.

PWA: Offline-First Surveys

The PWA can deliver and complete surveys entirely without network connectivity. Responses are queued locally and synced when the connection is restored.

How it works

Session preloading

Before the participant begins a survey, the PWA calls GET /api/v1/webapp/session/{session_id}/preload which returns everything needed to complete the survey offline:

• All questions with their configuration
• Section metadata and question ordering
• Pre-generated tokens for cognitive assessments and time pickers
• Pre-built URLs for external assessment webviews
• Any previously answered responses (for session resumption)

This means the client has the complete survey payload before the participant answers the first question.

Client-side survey engine

The OfflineSurveyEngine (in pwa/src/lib/surveyEngine.ts) drives the survey flow entirely on the client:

• Question progression: Advances through questions, respecting show_if conditional logic
• Section transitions: Detects when the participant enters a new section and shows interstitial messages
• Progress tracking: Calculates progress accounting for conditionally hidden questions
• Response editing: Supports rewinding to change previous answers (configurable per survey/section)

Response queue

The ResponseQueue (in pwa/src/lib/responseQueue.ts) manages offline response persistence:

• localStorage storage: Responses persist across browser restarts
• Deduplication: Same (session, question) pair is replaced, not duplicated
• Retry with backoff: Up to 10 attempts with exponential backoff
• Smart error handling: 4xx errors (permanent) are discarded; 5xx errors (temporary) are retried
• Auto-flush triggers:
  • Browser online event fires
  • Document becomes visible (tab refocused)
  • Survey completion (flushes all pending before marking complete)

Message cache

The MessageCache (in pwa/src/lib/messageCache.ts) preserves chat history across page refreshes:

• 24-hour TTL for cached messages
• Isolated by participant ID
• Graceful degradation on parse errors

Service worker

The service worker (src/static/sw.js) provides two layers of offline support:

1. Asset caching (cache-first)

Precaches m2c2kit cognitive assessment modules so they load instantly offline:

• Core libraries (@m2c2kit/core, session, addons)
• Assessment bundles (symbol-search, color-shapes)
• Fonts, images, and localization files

2. Cognitive result queueing (IndexedDB)

Intercepts POST /api/v1/cognitive/complete requests when offline:

• Stores the request in IndexedDB (iema-offline database)
• Returns a synthetic 200 { status: 'queued' } so the assessment UI completes normally
• Replays queued requests when connectivity returns via Background Sync

The service worker also intercepts GET /api/v1/cognitive/status to return locally cached completion status, so the survey can advance past cognitive questions even while offline.

Push notification integration

When a PWA participant is offline (no WebSocket connection), the server:

1. Sends a Web Push notification (see Push Notifications)
2. Creates a pending survey session in the database
3. When the participant opens the app, the session is available for preloading and offline completion
4. If the session isn't completed within the timeout window (default: 30 minutes), it expires

Telegram: Online Only

Telegram operates as a synchronous, server-driven channel with no offline capabilities:

• The server sends one question at a time
• Each response (button tap or text message) triggers a server action
• There is no client-side state management
• If the bot can't reach the Telegram API, the message is not delivered

Session timeout

Both frontends share the same timeout behavior: if a survey session isn't completed within SURVEY_TIMEOUT_MINUTES (default: 30), it expires and the participant can no longer respond.

Comparison

Capability	PWA	Telegram
Complete surveys offline	Yes	No
Response queueing	localStorage + auto-sync	N/A
Cognitive assessments offline	Yes (precached + IndexedDB queue)	No
Session resumption	Yes (preload returns answered responses)	Yes (server tracks state)
Message history on refresh	Yes (24h cache)	Yes (Telegram chat history)
Survey flow control	Client-driven	Server-driven