84 lines
5.5 KiB
Markdown
84 lines
5.5 KiB
Markdown
# 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).
|