nexo/README.md

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 intended plugin test app. The current transitional path is apps/client/.
• apps/mattermost/ is reserved for the original Mattermost app repository clone.
• services/core/ is the Mattermost server repository clone.
• services/push-proxy/ is reserved for the Mattermost push-proxy repository clone.
• 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:

bin/dev

Run Flutter package and flutter-test host checks:

bin/test
bin/lint

Start the core compose runtime:

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 the transitional apps/client test-host web build; 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/client && flutter run	Transitional path until apps/flutter-test exists
Test the plugin directly	cd packages/messaging_flutter && flutter test	Requires Flutter SDK
Run Android native unit tests	cd apps/client/android && ./gradlew testDebugUnitTest	Transitional path until apps/flutter-test exists

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/	Intended flutter-test app for package integration checks
apps/client/	Current transitional path for the flutter-test app
apps/mattermost/	Intended original Mattermost app repository clone
services/core/	Mattermost server repository clone and current compose runtime
services/push-proxy/	Intended Mattermost push-proxy repository clone
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/client/ only as the transitional apps/flutter-test path; 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 only upstream main in those staging clones. When main 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/client/README.md
• docs/README.md