# 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 and macOS share the unified Dart API boundary, but `../nexo/packages/messaging_flutter` currently exposes native runtime stubs for these platforms.
- **Dart Level Integration**: Sibling systems can keep the same host-facing calls (`MattermostPushClient` methods).
- **Native Implementation Extension**: Production APNS/macOS notification behavior must be implemented in the plugin native platform folders before these targets are treated as runtime-ready.

---

## 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:
   ```yaml
   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).
