🏗️ Offline-First Improvements

Comprehensive offline-first architecture enhancements for error-free operation when backend is unavailable.

📋 Table of Contents

1. Overview
2. Problem Statement
3. Solution Architecture
4. Implementation Details
5. Components Modified
6. Usage Guide
7. Testing
8. Expected Outcomes

🎯 Overview

GoGrab Space now features a sophisticated error-free offline-first architecture that:

• ✅ Eliminates console errors when backend is unavailable
• ✅ Provides seamless offline work - users can continue working without interruption
• ✅ Automatically syncs when backend becomes available
• ✅ Offers clear UI feedback about connection state
• ✅ Preserves data integrity across online/offline transitions

Key Innovation

The architecture centers around a new NetworkSyncStateService in @storage-system that acts as the single source of truth for all network and backend connectivity state. All sync-related services now consume this centralized service.

🔴 Problem Statement

Before Implementation

When the backend-api was offline, multiple services would spam the console with errors:

Root Cause

Services lacked awareness of network/backend state and attempted operations that would inevitably fail, resulting in:

• Console spam making debugging difficult
• Poor user experience with constant error messages
• Unnecessary network requests wasting resources
• No graceful degradation to offline mode

🏛️ Solution Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        @storage-system                               │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │              NetworkSyncStateService (NEW)                     │  │
│  │                                                                │  │
│  │  Signals:                                                      │  │
│  │  • isOnline          - Browser network status                  │  │
│  │  • isBackendAvailable - Backend HTTP health check              │  │
│  │  • isWebSocketConnected - Socket.IO connection state           │  │
│  │  • connectionState   - Combined state enum                     │  │
│  │  • canMakeApiCalls   - Safe to call HTTP APIs                  │  │
│  │  • canUseWebSocket   - Safe to use WebSocket                   │  │
│  │  • shouldSuppressErrors - Error suppression flag               │  │
│  │                                                                │  │
│  │  Events:                                                       │  │
│  │  • onBackendAvailable$ - Backend came online                   │  │
│  │  • onBackendUnavailable$ - Backend went offline                │  │
│  │  • onReconnected$ - Reconnection completed                     │  │
│  │  • onConnectionStateChange$ - State changed                    │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                              │                                       │
│  ┌───────────────────────────┼───────────────────────────────────┐  │
│  │     Enhanced Components   │                                    │  │
│  │                           ▼                                    │  │
│  │  • HttpMongoDBSyncAdapter - Uses canSync() before operations   │  │
│  │  • IntelligentSyncEngine - Backend availability aware          │  │
│  └───────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘
                               │
               Exposes signals │ via provider
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                   @libs-foundational/core-angular                     │
│                                                                       │
│  ┌──────────────────┐  ┌──────────────────┐  ┌────────────────────┐  │
│  │ SyncEngineService│  │RealtimeSyncService│  │UserJourneyTracker  │  │
│  │ • Pauses sync    │  │ • Smart reconnect │  │ • Skips when       │  │
│  │ • Error suppress │  │ • WS state track  │  │   offline          │  │
│  │ • Auto-resume    │  │ • Error suppress  │  │ • Auto-resume      │  │
│  └──────────────────┘  └──────────────────┘  └────────────────────┘  │
│                                                                       │
│  ┌──────────────────┐  ┌──────────────────┐                          │
│  │ SpaceApiService  │  │ UserApiService   │                          │
│  │ • Cache fallback │  │ • Silent skip    │                          │
│  │ • Network errors │  │ • Graceful null  │                          │
│  │   → use cache    │  │   returns        │                          │
│  └──────────────────┘  └──────────────────┘                          │
└──────────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                        @libs-ui/shared-ui                             │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │ OfflineIndicatorComponent (NEW)                                 │  │
│  │ • Shows "Offline Mode" banner                                   │  │
│  │ • Shows "Reconnecting..." state                                 │  │
│  │ • Auto-hides when online                                        │  │
│  └────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘

Why This Architecture?

1. Single Source of Truth - @storage-system owns all sync/network state
2. No Duplication - Services consume NetworkSyncStateService, don't recreate
3. Clean Dependency Flow - storage-system → core-angular (not circular)
4. Centralized Error Suppression - One place to control logging behavior

🔧 Implementation Details

1. NetworkSyncStateService

Location: libs/libs-foundational/storage-system/src/sync/services/network-sync-state.service.ts

The foundation for ALL offline-first behavior.

// Connection states
export type ConnectionState = 
  | 'online'              // Backend available, full sync
  | 'offline'             // Browser offline, local-only
  | 'backend-unavailable' // Browser online but backend down
  | 'reconnecting';       // Attempting to reconnect

// Key API
readonly isOnline = signal<boolean>(navigator.onLine);
readonly isBackendAvailable = signal<boolean>(false);
readonly isWebSocketConnected = signal<boolean>(false);

readonly connectionState = computed<ConnectionState>(() => {
  if (!this._isOnline()) return 'offline';
  if (this._reconnecting) return 'reconnecting';
  if (!this._isBackendAvailable()) return 'backend-unavailable';
  return 'online';
});

readonly canMakeApiCalls = computed(() => 
  this._isOnline() && this._isBackendAvailable()
);

readonly canUseWebSocket = computed(() => 
  this.canMakeApiCalls() && this.isWebSocketConnected()
);

// Events for coordinated recovery
readonly onBackendAvailable$: Observable<void>;
readonly onBackendUnavailable$: Observable<void>;
readonly onReconnected$: Observable<void>;

Health Check with Exponential Backoff

// Backoff intervals: 5s → 10s → 20s → 40s → 60s (max)
private healthCheckIntervals = [5000, 10000, 20000, 40000, 60000];

private async performHealthCheck(): Promise<boolean> {
  try {
    const response = await firstValueFrom(
      this.http.get<{ status: string }>(this.healthCheckUrl, {
        headers: { 'X-Health-Check': 'true' }
      }).pipe(timeout(5000))
    );
    return response?.status === 'ok';
  } catch {
    return false;
  }
}

2. Provider Configuration

Location: libs/libs-foundational/storage-system/src/sync/providers/provide-network-sync-state.ts

// In app.config.ts
provideNetworkSyncState({
  apiBaseUrl: environment.backendApiUrl,
  healthCheckUrl: '/api/health',
  maxErrorLogs: 3,          // Suppress after 3 errors
  verbose: isDevMode(),     // Verbose logging in dev
  autoInitialize: true      // Start health checks on init
})

3. Error Suppression Strategy

The service tracks error count and suppresses repetitive logging:

// Only log first N errors, then suppress
recordError(): boolean {
  this._errorCount.update(c => c + 1);
  return this._errorCount() <= this.config.maxErrorLogs;
}

shouldSuppressErrors(): boolean {
  return this._errorCount() >= this.config.maxErrorLogs;
}

// Reset on successful connection
resetErrorCount(): void {
  this._errorCount.set(0);
}

📦 Components Modified

Storage System (@storage-system)

Core Angular (@libs-foundational/core-angular)

UI Components (@libs-ui/shared-ui)

App Configuration (gograb-space)

📖 Usage Guide

Consuming NetworkSyncStateService

import { NetworkSyncStateService } from '@storage-system';

@Injectable({ providedIn: 'root' })
export class MyService {
  private readonly networkState = inject(NetworkSyncStateService);

  async doSomethingWithBackend(): Promise<void> {
    // Check before making API calls
    if (!this.networkState.canMakeApiCalls()) {
      console.log('Backend unavailable - queuing operation');
      return;
    }

    try {
      await this.http.get('/api/data').toPromise();
    } catch (error) {
      // Only log if not suppressed
      if (!this.networkState.shouldSuppressErrors()) {
        console.error('API call failed:', error);
      }
    }
  }
}

Listening for Reconnection Events

export class MySyncService {
  private readonly networkState = inject(NetworkSyncStateService);
  private readonly destroyRef = inject(DestroyRef);

  constructor() {
    // Trigger sync when backend becomes available
    this.networkState.onBackendAvailable$.pipe(
      takeUntilDestroyed(this.destroyRef)
    ).subscribe(() => {
      console.log('Backend available - syncing now');
      this.networkState.resetErrorCount();
      this.performSync();
    });
  }
}

Using the Offline Indicator Component

<!-- Add to app.component.html or layout -->
<ux-offline-indicator></ux-offline-indicator>

<!-- Rest of your app -->
<router-outlet></router-outlet>

import { OfflineIndicatorComponent } from '@shared-ui';

@Component({
  standalone: true,
  imports: [OfflineIndicatorComponent, RouterOutlet],
  template: `
    <ux-offline-indicator></ux-offline-indicator>
    <router-outlet></router-outlet>
  `
})
export class AppComponent {}

Exposing Connection State in UI

@Component({
  template: `
    @if (isOffline()) {
      <div class="offline-notice">
        Working offline - changes saved locally
      </div>
    }
  `
})
export class MyComponent {
  private networkState = inject(NetworkSyncStateService);
  isOffline = computed(() => !this.networkState.canMakeApiCalls());
}

🧪 Testing

Manual Testing Checklist

1. Start app with backend offline

   • No console errors on startup
   • Offline indicator shows
   • App loads and is usable

2. Work offline

   • Can navigate between pages
   • Can modify data (saved locally)
   • No repeated error messages

3. Start backend while app running

   • Backend detected within 60 seconds
   • Sync automatically resumes
   • Offline indicator disappears

4. Kill backend while working

   • Graceful handling (no crash)
   • Offline indicator appears
   • Work can continue

Simulating Offline Mode

// In browser console:
// Simulate offline
window.__networkState__.setBackendUnavailable();

// Simulate online
window.__networkState__.setBackendAvailable();

✅ Expected Outcomes

Connection State Flow

Browser Online + Backend Up = "online" (full functionality)
                    │
                    ▼ Backend goes down
                    │
Browser Online + Backend Down = "backend-unavailable"
                    │         (local storage works,
                    │          no sync attempts)
                    │
                    ▼ Health check succeeds
                    │
              "reconnecting" (brief state)
                    │
                    ▼ Sync completes
                    │
              "online" (back to normal)

📁 File Reference

New Files Created

• libs/libs-foundational/storage-system/src/sync/services/network-sync-state.service.ts
• libs/libs-foundational/storage-system/src/sync/providers/provide-network-sync-state.ts
• libs/libs-ui/shared-ui/src/lib/components/offline-indicator/offline-indicator.component.ts
• libs/libs-ui/shared-ui/src/lib/components/offline-indicator/index.ts

Files Modified

• libs/libs-foundational/storage-system/src/sync/services/index.ts
• libs/libs-foundational/storage-system/src/sync/providers/index.ts
• libs/libs-foundational/storage-system/src/sync/services/intelligent-sync-engine.ts
• libs/libs-foundational/storage-system/src/sync/adapters/http-mongodb-sync-adapter.ts
• libs/libs-foundational/core-angular/src/lib/services/sync-engine.service.ts
• libs/libs-foundational/core-angular/src/lib/services/space-api.service.ts
• libs/libs-foundational/core-angular/src/lib/services/user-api.service.ts
• libs/libs-foundational/core-angular/src/lib/services/realtime-sync.service.ts
• libs/libs-foundational/core-angular/src/lib/modules/user-journey-tracker/user-journey-tracker.service.ts
• libs/libs-ui/shared-ui/src/lib/components/index.ts
• apps/gograb-space/src/app/app.config.ts

🔮 Future Enhancements

1. Offline Data Queue Visualization - Show users pending changes
2. Conflict Resolution UI - When local and server data conflict
3. Background Sync API - Use Service Worker for more robust sync
4. Selective Sync - Allow users to choose what syncs when
5. Bandwidth-Aware Sync - Adjust sync based on connection quality

📚 Related Documentation

• Storage System Overview
• Real-Time Sync Architecture
• SyncEngine Service

Last Updated: December 2025
Implementation Status: ✅ Complete
Session: 7