nomadcode/apps/client/push-notification-todo.md

Client Integration Handoff & Migration Notes

Important

Host App Integration Standard As of the mattermost-push-plugin-extraction milestone, all native FCM services, Room DB structures, JJWT signature verification, inline reply/dismiss receivers, notification builders, and ACK request handling have been successfully extracted into the local Flutter plugin package. The package now lives in the nexo monorepo at ../nexo/packages/messaging_flutter with Dart package name nexo_messaging. The host-facing interface keeps Mattermost naming because this app consumes the Mattermost-compatible messaging boundary.

Do NOT edit native push files directly inside this host app repository (apps/client/android). All native push logic and platform services now reside in and must be maintained within the plugin repository.

---

1. Responsibility Split & Boundaries

To keep host architectures generic and lightweight, we maintain a strict boundary between host logic and external dependency plugins.

1.1 Mattermost Push Notification Boundary

• Host Application (apps/client) Responsibilities:
  1. Firebase Manifest & Metadata:
     • google-services.json inside apps/client/android/app/
     • Initializing Firebase inside lib/src/app/bootstrap.dart via Firebase.initializeApp().
  2. Credential Plumbing:
     • Host standardizes all credential synchronization through the MattermostPushClient interface rather than accessing the native plugin directly:
       • Local smoke credentials may be provided as ignored assets/mattermost_credentials.json.
       • Login: Sync authorization credentials via pushClient.setAuthToken(serverUrl, token).
       • Logout: Revoke and clear credentials via pushClient.setAuthToken(serverUrl, '').
       • Asymmetric Signing Keys: Register server public keys via pushClient.setSigningKey(serverUrl, publicKey).
  3. App Navigation Callbacks:
     • Wire navigation delegates on the MattermostPushClient interface:
       • onNavigateToChannel = (serverUrl, channelId) => ...: Handles custom routing logic to channel view on notification click.
       • onNavigateToThread = (serverUrl, rootId) => ...: Handles CRT thread view navigation.
  4. Device Token Sync:
     • Listen to token registration callbacks via the onDeviceTokenReady callback on MattermostPushClient interface, and forward the target device token back to the Mattermost backend server.
     • Note: Production calls to NexoMessagingPlugin.instance are strictly isolated and encapsulated within the MattermostPushPluginClient adapter implementation, maintaining a generic, testable host bootstrap.
• Nexo Messaging Plugin (nexo_messaging) Responsibilities:
  • Intercepting incoming FCM pushes via Kotlin services (NexoFirebaseMessagingService).
  • Parsing payloads and verifying cryptographic signatures with JJWT.
  • Interacting with local SQLite database (Room DB).
  • Building native system notifications, dismissing ACKs, and inline replies.

1.2 Proto-socket Integration Boundary

• Host Application (apps/client) Responsibilities:
  1. Local Dependency Setup:
     • Reference the local path package proto_socket in pubspec.yaml.
  2. Facade Configuration:
     • Read configuration defaults through ProtoSocketEndpointConfig.fromEnv().
     • Wire connections via ProtoSocketLifecycle facade inside the bootstrap stream.
  3. No-Op Auto-connect:
     • By default, bootstrap configures the lifecycle with enabled: false and uses NoopProtoSocketConnector().
     • Real socket initialization and active transport loops are decoupled from bootstrap and deferred to client UI activation.

---

2. Platform Target Status & Expansion

2.1 Web Target

• Supported in core configuration bootstrap.
• Socket facade safely falls back to standard WebSocket interfaces or no-op handlers in non-supported native environments.

2.2 Android Target

• Fully operational for Mattermost push notifications.
• Integrates Firebase Cloud Messaging, JJWT verification, Room Database, and native background broadcasts.

2.3 iOS Target Status & Native Extension

• iOS is fully integrated into the unified Dart API boundary.
• Dart Level Integration: Sibling systems can target iOS using identical calls (MattermostPushClient methods).
• Native Implementation Extension: Sibling repos can implement native APNS delegate receivers inside the iOS project folder without needing to modify common Dart facades or common bootstrap parameters.

---

3. Reference Sibling Repo Alignment & Replacement

When replicating this integration boundary in sibling repositories (../iop and ../alt):

Checklist for Sibling Alignment:

1. Firebase Credential Sync: Provide valid google-services.json (Android) and GoogleService-Info.plist (iOS) in respective project roots.
2. Local Path Imports: Ensure pubspec.yaml points correctly to the actual sibling workspace dependency paths:

   nexo_messaging:
     path: ../../../nexo/packages/messaging_flutter
   proto_socket:
     path: ../../../proto-socket/dart
   

   Note: If sibling repositories utilize different directory hierarchies (e.g. nested packages or monorepo namespaces), the relative path must be adjusted accordingly to point to the correct workspace location of the shared libraries.
3. Endpoint Realization: Initialize client configuration with workspace endpoints matching your target backend (e.g. IOP portal routing or ALT quant metrics server).