140 lines
6.6 KiB
Markdown
140 lines
6.6 KiB
Markdown
# nexo
|
|
|
|
`nexo` is a Flutter messaging and notification package workspace. The main
|
|
deliverable is `packages/messaging_flutter`: a reusable package that lets many
|
|
Flutter apps integrate messaging and push-notification behavior without each app
|
|
reimplementing the same native runtime.
|
|
|
|
Mattermost upstream repositories are kept as references around the package:
|
|
`apps/mattermost` for the original Mattermost app, `services/core` for the
|
|
server, and `services/push-proxy` for the push server. This repository does not
|
|
contain a dedicated nexo product app.
|
|
|
|
## Name
|
|
|
|
`nexo` comes from `nexus`: a connection point where apps, messages,
|
|
notifications, and service infrastructure meet.
|
|
|
|
## Current Status
|
|
|
|
- `packages/messaging_flutter/` is the main product surface: an Android-first Flutter messaging and push-notification plugin package.
|
|
- `apps/flutter-test/` is the plugin test app.
|
|
- `apps/mattermost/` is the original Mattermost mobile app repository snapshot (see `apps/mattermost/UPSTREAM.md`).
|
|
- `services/core/` is the Mattermost server repository clone.
|
|
- `services/push-proxy/` is the Mattermost push-proxy repository snapshot (see `services/push-proxy/UPSTREAM.md`).
|
|
- Public package, import, and native identifiers are being moved to Nexo-owned names.
|
|
- iOS and macOS plugin scaffolds exist, but Android is the current implementation target.
|
|
|
|
## Quick Start
|
|
|
|
Show development entrypoints:
|
|
|
|
```sh
|
|
bin/dev
|
|
```
|
|
|
|
Run Flutter package and `flutter-test` host checks:
|
|
|
|
```sh
|
|
bin/test
|
|
bin/lint
|
|
```
|
|
|
|
Start the core compose runtime:
|
|
|
|
```sh
|
|
cd services/core/compose
|
|
cp .env.example .env
|
|
docker compose up
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Purpose | Command | Notes |
|
|
| --- | --- | --- |
|
|
| Show development entrypoints | `bin/dev` | Prints test host, plugin, and core compose commands |
|
|
| Run default tests | `bin/test` | Runs Flutter tests; skips Go tests by default |
|
|
| Run default lint | `bin/lint` | Runs Flutter analyze; skips Go vet by default |
|
|
| Run default build | `bin/build` | Runs configured app builds; skips `apps/flutter-test` web build when web is not configured and skips Go build by default |
|
|
| Include server Go tests | `NEXO_CORE_GO_TEST=1 bin/test` | Requires local `go` |
|
|
| Include server Go vet | `NEXO_CORE_GO_LINT=1 bin/lint` | Requires local `go` |
|
|
| Include server Go build | `NEXO_CORE_GO_BUILD=1 bin/build` | Requires local `go` |
|
|
| Run the `flutter-test` host directly | `cd apps/flutter-test && flutter run` | Requires Flutter SDK |
|
|
| Test the plugin directly | `cd packages/messaging_flutter && flutter test` | Requires Flutter SDK |
|
|
| Run Android native unit tests | `cd apps/flutter-test/android && ./gradlew testDebugUnitTest` | Requires Android SDK |
|
|
|
|
The `bin/*` helpers skip checks when a required local tool is unavailable. Note
|
|
any skipped checks in work reports.
|
|
|
|
## Structure
|
|
|
|
| Path | Role |
|
|
| --- | --- |
|
|
| `packages/messaging_flutter/` | Main Flutter messaging and push-notification package |
|
|
| `apps/flutter-test/` | `flutter-test` app for package integration checks |
|
|
| `apps/mattermost/` | Mattermost mobile app repository snapshot |
|
|
| `services/core/` | Mattermost server repository clone and current compose runtime |
|
|
| `services/push-proxy/` | Mattermost push-proxy repository snapshot |
|
|
| `docs/` | Cross-module product, migration, and operations notes |
|
|
| `bin/` | Workspace helper entrypoints |
|
|
| `agent-ops/` | Agent rules, domain rules, and common skill entrypoints |
|
|
|
|
## Work Context
|
|
|
|
- Start by reading `AGENTS.md`, then `agent-ops/rules/project/rules.md`.
|
|
- Follow path-specific domain rules under `agent-ops/rules/project/domain/*/rules.md`.
|
|
- For standard tasks such as README, plan, review, or commit/push, route through `agent-ops/skills/common/router.md`.
|
|
- Treat `packages/messaging_flutter/` as the primary product. App-specific product UI and business logic belong in consuming apps outside this repository.
|
|
- Treat `apps/flutter-test/` only as the plugin integration test host; do not grow it into a product app or duplicate plugin internals there.
|
|
- Treat `apps/mattermost`, `services/core`, and `services/push-proxy` as original Mattermost repository clones, not as nexo-owned app or server products.
|
|
- Do not change `services/core/UPSTREAM.md` baseline information without an explicit upstream decision.
|
|
- Keep upstream working clones outside this repository under a sibling/external `mattermost/` staging folder, one clone for each original repository.
|
|
- Track each upstream repository on its recorded staging branch: `main` for `mattermost-mobile`, and `master` for `mattermost` and `mattermost-push-proxy`. When a tracked branch changes or a refresh is intentionally scheduled, take a fresh snapshot from staging and open a merge request into this repository.
|
|
- Record the exact upstream commit SHA for every snapshot that enters this repository.
|
|
- Prefer one merge request per upstream repository snapshot: `apps/mattermost`, `services/core`, or `services/push-proxy`.
|
|
- Never auto-apply staging updates into this repository; review the snapshot diff and run the relevant smoke checks first.
|
|
- Keep nexo-specific patches outside the upstream snapshot where possible, using compose, docs, wrappers, or small explicit patches.
|
|
|
|
## Development Flow
|
|
|
|
1. Read the domain rule for the path you will change.
|
|
2. Make focused changes inside the owning module.
|
|
3. Run the smallest useful verification for the change.
|
|
4. Use `bin/test`, `bin/lint`, or `bin/build` when workspace-level checks are needed.
|
|
5. Use `services/core/compose/` when runtime server verification is needed.
|
|
|
|
## Environment Variables
|
|
|
|
### Core Compose
|
|
|
|
| Name | Description | Required |
|
|
| --- | --- | --- |
|
|
| `NEXO_DB_PASSWORD` | Password for the Postgres `mmuser` account | Yes |
|
|
| `NEXO_SITE_URL` | Site URL used by the core service | Yes |
|
|
| `NEXO_CORE_PORT` | Host port mapped to core `8065` | No |
|
|
| `NEXO_PUSH_PROXY_PORT` | Host port mapped to push-proxy `8066` | No |
|
|
|
|
See `services/core/compose/.env.example` for example values. Do not commit real
|
|
`.env` files or runtime data. The Docker network subnet is fixed to
|
|
`172.38.0.0/16`; reserve this range for nexo and do not reuse it for other Docker
|
|
networks.
|
|
|
|
### Optional Verification
|
|
|
|
| Name | Description | Default |
|
|
| --- | --- | --- |
|
|
| `NEXO_CORE_GO_TEST` | Run server Go tests from `bin/test` | `0` |
|
|
| `NEXO_CORE_GO_LINT` | Run server Go vet from `bin/lint` | `0` |
|
|
| `NEXO_CORE_GO_BUILD` | Run server Go build from `bin/build` | `0` |
|
|
|
|
## Reference Documents
|
|
|
|
- `AGENTS.md`
|
|
- `agent-ops/rules/project/rules.md`
|
|
- `agent-ops/skills/common/router.md`
|
|
- `services/core/UPSTREAM.md`
|
|
- `services/core/compose/README.md`
|
|
- `packages/messaging_flutter/README.md`
|
|
- `packages/messaging_flutter/docs/android-test-environment.md`
|
|
- `apps/flutter-test/README.md`
|
|
- `docs/README.md`
|