nexo

nexo is a messaging and notification service workspace that keeps the server core, Flutter client, and Flutter push-notification package together.

The current goal is to provide a Nexo-owned messaging service surface while keeping the current server, client, and push runtime verifiable during the transition.

Name

nexo comes from nexus: a connection point where apps, messages, notifications, and service infrastructure meet.

Current Status

• services/core/ is the messaging server core and compose runtime.
• packages/messaging_flutter/ is an Android-first Flutter push-notification plugin.
• apps/client/ is the Flutter client and integration test host for the plugin.
• 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 client 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 client, 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 client 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 client directly	cd apps/client && flutter run	Requires a device or emulator
Test the plugin directly	cd packages/messaging_flutter && flutter test	Requires Flutter SDK
Run Android native unit tests	cd apps/client/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
services/core/	Messaging server core, webapp, and API docs
services/core/compose/	Compose setup for core, Postgres, and push-proxy
packages/messaging_flutter/	Flutter push notification and messaging plugin
apps/client/	Flutter client and integration test host
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.
• Do not change services/core/UPSTREAM.md baseline information without an explicit upstream decision.
• Keep product-specific services/core/ changes small and easy to compare against upstream.
• Keep apps/client/ as a thin consumer test host; do not duplicate plugin internals there.

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