Merge pull request #32 from getditto/cx-541-peer-sync-status

CX-541:  Peer Sync Status

Author: biozal

README.md

@@ -54,6 +54,69 @@ The `PeerListView` uses Ditto's presence observer to provide real-time updates:
 - No manual refresh required
 
 
+## `PeerSyncStatusView`
+
+The `PeerSyncStatusView` provides a real-time interface for monitoring the synchronization status between your device and connected peers in the Ditto mesh network. This tool queries Ditto's internal `system:data_sync_info` collection to display detailed sync session information, helping developers debug data synchronization issues and monitor sync health.
+
+### Usage
+
+The `PeerSyncStatusView` can be used as a standalone widget in your Flutter application:
+
+```dart
+import 'package:ditto_flutter_tools/ditto_flutter_tools.dart';
+
+// In your widget build method
+Scaffold(
+  appBar: AppBar(title: Text('Peer Sync Status')),
+  body: PeerSyncStatusView(ditto: myDittoInstance),
+)
+```
+
+### Features
+
+The peer sync status view provides:
+
+1. **Connection Status Grouping** - Separates peers into "Connected" and "Not Connected" sections for quick status overview
+2. **Peer Type Identification** - Distinguishes between Cloud Server and Peer Device connections
+3. **Sync Session Information** - Shows the synchronization session status for each peer
+4. **Database Commit Tracking** - Displays which local database commit ID each peer has synced to
+5. **Last Update Timestamps** - Shows when the last sync update was received from each peer
+6. **Real-time Updates** - Automatically updates as sync status changes
+
+### Information Displayed
+
+For each peer, the view shows:
+- **Peer Type** - Either "Cloud Server" for Ditto Big Peer or "Peer Device" for mesh network peers
+- **Peer ID** - The unique identifier for the peer
+- **Connection Status** - Visual indicator showing if the peer is currently connected
+- **Sync Commit ID** - The local database commit ID that this peer has synced up to (when available)
+- **Last Update Time** - Formatted timestamp showing when the last update was received (displays as "Today", "Yesterday", or full date/time)
+
+### Data Source & DQL Strict Mode Support
+
+The `PeerSyncStatusView` automatically detects your Ditto instance's DQL strict mode setting and uses the appropriate query:
+
+This provides access to Ditto's internal synchronization metadata, giving insights into:
+- Which peers have active sync sessions (`Connected` vs `Not Connected`)
+- How up-to-date each peer is with local data changes (commit IDs)
+- When synchronization last occurred with each peer (timestamps)
+
+### Use Cases
+
+This view is particularly useful for:
+- **Debugging sync issues** - Identify which peers are not receiving updates
+- **Monitoring sync latency** - Check when peers last synchronized  
+- **Verifying cloud connectivity** - Confirm that devices are syncing with Ditto Cloud
+- **Understanding sync topology** - See which peers are actively participating in data synchronization
+- **Performance monitoring** - Track sync commit progress across the network
+
+### Implementation Notes
+
+- **Automatic Mode Detection**: No configuration needed - works with both DQL strict modes
+- **Real-time Updates**: Uses Ditto store observers for live sync status monitoring  
+- **Proper Lifecycle Management**: Handles widget disposal cleanly to prevent memory leaks
+- **Error Handling**: Gracefully handles cases where sync data is unavailable
+
 ## `DiskUsageView`
 
 The `DiskUsageView` provides a comprehensive interface for monitoring Ditto database disk usage and exporting data for debugging or backup purposes. This tool helps developers understand storage consumption and provides convenient export functionality for both database files and logs.

example/README.md

@@ -25,6 +25,22 @@ This example app showcases all the diagnostic tools available in the `ditto_flut
   - Track database growth over time
   - Identify storage optimization opportunities
 
+- **Permissions Health**: Check app permissions status
+  - Monitor Bluetooth, WiFi, and location permissions
+  - View permission states and requirements
+  - Get guidance on enabling required permissions
+
+- **System Settings**: Access device-specific settings
+  - Open relevant system settings pages
+  - Quick access to Bluetooth and WiFi settings
+  - Platform-specific configuration options
+
+### 🔄 Peer Sync Status
+- **Peer Sync Status**: Monitor synchronization between specific peers
+  - View sync status for individual peer connections
+  - Track data flow between devices
+  - Identify sync bottlenecks and issues
+
 ## Quick Start
 
 ### Prerequisites
@@ -126,27 +142,286 @@ Enable the following entitlements in `macos/Runner/DebugProfile.entitlements`:
 2. Tap on "Disk Usage"
 3. View current database size and storage metrics
 
+### Monitoring Permissions Health
+1. Launch the app
+2. Tap on "Permissions Health"
+3. View the status of all required permissions
+4. Follow guidance to enable missing permissions
+
+### Accessing System Settings
+1. Launch the app
+2. Tap on "System Settings"
+3. Access device-specific settings for Bluetooth and WiFi
+4. Configure network and connectivity options
+
+### Viewing Peer Sync Status
+1. Launch the app
+2. Tap on "Peer Sync Status"
+3. Monitor synchronization between specific peers
+4. Track data flow and identify sync issues
+
 ## Project Structure
 
 ```
 example/
 ├── lib/
-│   ├── main.dart                 # App entry point and main UI
-│   ├── providers/
-│   │   └── ditto_provider.dart   # Ditto SDK initialization
+│   ├── main.dart                 # App entry point and routing configuration
+│   ├── constants/
+│   │   └── routes.dart           # Centralized route definitions
 │   ├── services/
+│   │   ├── ditto_service.dart    # Ditto SDK initialization and management
 │   │   └── subscription_service.dart # Manages sync subscriptions
+│   ├── screens/                  # Individual screen implementations
+│   │   ├── peers_list_screen.dart
+│   │   ├── sync_status_screen.dart
+│   │   ├── peer_sync_status_screen.dart
+│   │   ├── permissions_health_screen.dart
+│   │   ├── disk_usage_screen.dart
+│   │   └── system_settings_screen.dart
 │   └── widgets/
-│       └── presence.dart         # Presence visualization
+│       └── main_list_view.dart   # Main navigation interface
 ├── android/                      # Android platform files
 ├── ios/                          # iOS platform files
 ├── macos/                        # macOS platform files
 ├── web/                          # Web platform files
 └── pubspec.yaml                  # Dependencies
 ```
 
+## Routing Architecture
+
+This app uses [Beamer](https://pub.dev/packages/beamer) for navigation, providing a clean and maintainable routing system. All routes are centrally defined to avoid magic strings and ensure consistency.
+
+### Route Management
+
+Routes are defined in `lib/constants/routes.dart` using top-level constants:
+
+```dart
+// Route constants - centralized location for all app routes
+const String homeRoute = '/';
+const String peersRoute = '/peers';
+const String syncStatusRoute = '/sync-status';
+const String peerSyncStatusRoute = '/peer-sync-status';
+const String permissionsHealthRoute = '/permissions-health';
+const String diskUsageRoute = '/disk-usage';
+const String systemSettingsRoute = '/system-settings';
+```
+
+### Navigation Setup
+
+The routing is configured in `main.dart` using Beamer's `RoutesLocationBuilder`:
+
+```dart
+final beamerDelegate = BeamerDelegate(
+  initialPath: homeRoute,
+  locationBuilder: RoutesLocationBuilder(
+    routes: {
+      homeRoute: (context, state, data) => MainListView(
+        dittoService: dittoService,
+        subscriptionService: subscriptionService,
+      ),
+      peersRoute: (context, state, data) => PeersListScreen(
+        ditto: dittoService.ditto,
+      ),
+      // ... other routes
+    },
+  ),
+);
+```
+
+### Navigation Usage
+
+Navigate between screens using Beamer:
+
+```dart
+// Navigate to a specific route
+Beamer.of(context).beamToNamed(peersRoute);
+
+// Navigate back
+Beamer.of(context).beamBack();
+```
+
 ## Customization
 
+### Adding a New Page
+
+To add a new page to the app, follow these steps:
+
+#### 1. Create the Route Constant
+
+Add your new route to `lib/constants/routes.dart`:
+
+```dart
+const String myNewPageRoute = '/my-new-page';
+```
+
+#### 2. Create the Screen Widget
+
+Create a new file `lib/screens/my_new_page_screen.dart`:
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:ditto_flutter_tools/ditto_flutter_tools.dart';
+
+class MyNewPageScreen extends StatelessWidget {
+  final Ditto ditto;
+
+  const MyNewPageScreen({
+    super.key,
+    required this.ditto,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('My New Page'),
+      ),
+      body: const Center(
+        child: Text('This is my new page!'),
+      ),
+    );
+  }
+}
+```
+
+#### 3. Add the Route to main.dart
+
+Import your new screen and add it to the routes map in `main.dart`:
+
+```dart
+import 'screens/my_new_page_screen.dart';
+import 'constants/routes.dart';
+
+// In the BeamerDelegate configuration:
+final beamerDelegate = BeamerDelegate(
+  initialPath: homeRoute,
+  locationBuilder: RoutesLocationBuilder(
+    routes: {
+      // ... existing routes
+      myNewPageRoute: (context, state, data) => MyNewPageScreen(
+        ditto: dittoService.ditto,
+      ),
+    },
+  ),
+);
+```
+
+#### 4. Add Navigation Button
+
+Add a navigation button to `lib/widgets/main_list_view.dart`:
+
+```dart
+// Import the routes
+import '../constants/routes.dart';
+
+// Add a new ListTile in the appropriate section:
+ListTile(
+  leading: Container(
+    width: 32,
+    height: 32,
+    decoration: BoxDecoration(
+      color: Colors.blue,
+      borderRadius: BorderRadius.circular(8),
+    ),
+    child: const Icon(
+      Icons.new_page_icon,
+      color: Colors.white,
+      size: 20,
+    ),
+  ),
+  title: const Text("My New Page"),
+  trailing: Icon(Icons.chevron_right,
+      color: Theme.of(context).colorScheme.onSurfaceVariant),
+  onTap: () => Beamer.of(context).beamToNamed(myNewPageRoute),
+),
+```
+
+#### 5. Complete Example
+
+Here's a complete example of adding a "Data Explorer" page:
+
+**Step 1 - Add route constant:**
+```dart
+// In lib/constants/routes.dart
+const String dataExplorerRoute = '/data-explorer';
+```
+
+**Step 2 - Create screen:**
+```dart
+// lib/screens/data_explorer_screen.dart
+import 'package:flutter/material.dart';
+import 'package:ditto_flutter_tools/ditto_flutter_tools.dart';
+
+class DataExplorerScreen extends StatelessWidget {
+  final Ditto ditto;
+
+  const DataExplorerScreen({
+    super.key,
+    required this.ditto,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text('Data Explorer'),
+      ),
+      body: FutureBuilder(
+        future: ditto.store.execute('SELECT * FROM collections'),
+        builder: (context, snapshot) {
+          if (snapshot.hasData) {
+            return ListView.builder(
+              itemCount: snapshot.data!.length,
+              itemBuilder: (context, index) {
+                return ListTile(
+                  title: Text('Collection ${index + 1}'),
+                );
+              },
+            );
+          }
+          return const Center(child: CircularProgressIndicator());
+        },
+      ),
+    );
+  }
+}
+```
+
+**Step 3 - Add to main.dart:**
+```dart
+// Add import
+import 'screens/data_explorer_screen.dart';
+
+// Add to routes map
+dataExplorerRoute: (context, state, data) => DataExplorerScreen(
+  ditto: dittoService.ditto,
+),
+```
+
+**Step 4 - Add navigation button:**
+```dart
+// In lib/widgets/main_list_view.dart, add to the SYSTEM section:
+ListTile(
+  leading: Container(
+    width: 32,
+    height: 32,
+    decoration: BoxDecoration(
+      color: Colors.teal,
+      borderRadius: BorderRadius.circular(8),
+    ),
+    child: const Icon(
+      Icons.explore,
+      color: Colors.white,
+      size: 20,
+    ),
+  ),
+  title: const Text("Data Explorer"),
+  trailing: Icon(Icons.chevron_right,
+      color: Theme.of(context).colorScheme.onSurfaceVariant),
+  onTap: () => Beamer.of(context).beamToNamed(dataExplorerRoute),
+),
+```
+
 ### Adding Custom Subscriptions
 
 Edit `lib/services/subscription_service.dart` to add your own subscriptions:

example/lib/constants/routes.dart

@@ -0,0 +1,8 @@
+// Route constants - centralized location for all app routes
+const String homeRoute = '/';
+const String peersRoute = '/peers';
+const String syncStatusRoute = '/sync-status';
+const String peerSyncStatusRoute = '/peer-sync-status';
+const String permissionsHealthRoute = '/permissions-health';
+const String diskUsageRoute = '/disk-usage';
+const String systemSettingsRoute = '/system-settings';