Skip to main content

ADR 0019 — EthioConnect Branding and Dart/Flutter Documentation

Status: Accepted Context date: 2026-07-22

Context​

The platform has been developed under the working name "Communication BaaS" — a description of the service category rather than a product name. With the documentation site live (ADR 0018), a tenant admin portal, and SDKs for JavaScript, Swift, and Kotlin shipped, the platform is entering its developer-facing phase and needs a brand that can appear in documentation, the portal, and marketing surfaces.

At the same time, Flutter has become a significant integration target. There is no Dart SDK yet, and building one to the standard set by ADR 0017 (typed models, resource facades, signaling state machine with session resume, platform-idiomatic concurrency) takes time. But the REST and WebSocket contracts are stable and fully specified in contracts/, and Flutter developers can integrate against them today with standard pub.dev packages. Waiting for a native SDK before publishing any Flutter guidance would leave the fastest-growing client ecosystem without documentation.

Forces at play:

  1. Brand vs. identifiers. Renaming prose is cheap; renaming published package names (@comm-baas/* on npm, the CommBaaS Swift package, com.commbaas:sdk on Maven) is a breaking change for every consumer and requires a coordinated major-version migration.
  2. Honesty in documentation. Publishing a "Flutter SDK" section without a published package would mislead developers. An integration guide that says exactly what exists — raw contracts plus standard packages — does not.
  3. Docs-as-contract drift. An integration guide documents endpoints and message types directly, so it must be kept in sync with contracts/openapi/* and contracts/ws-protocol/* until the native SDK abstracts them.

Decision​

1. Brand the developer-facing platform "EthioConnect"​

All prose in the documentation site (docs-site/docs/**, excluding the generated api-reference/) refers to the product as EthioConnect. The repo-root ADR sources are updated in the same pass so the docs sync script (ADR 0018) does not revert the rename.

Explicitly unchanged:

  • npm package names (@comm-baas/types, @comm-baas/server-sdk, @comm-baas/client-sdk, @comm-baas/react)
  • the Swift package and module name CommBaaS
  • the Maven coordinate com.commbaas:sdk
  • API key prefixes (cb_<prefix>.<secret>), code identifiers, URLs, and repository names

A coordinated package rename, if ever done, will be its own ADR with a major-version migration plan. Until then, docs state the product name in prose and the existing identifiers in code.

2. Docusaurus remains the single developer-facing surface​

The EthioConnect documentation site (Docusaurus, per ADR 0018) serves both narrative documentation and the interactive API explorer generated from the OpenAPI specs. No separate marketing-docs or API-portal tool is introduced; branding is applied within the existing site.

3. Ship Dart/Flutter integration docs now​

A six-page Flutter (Dart) section is added under docs-site/docs/sdks/flutter/ (overview, authentication, rooms, signaling, media, presence & notifications). It is an integration guide, not an SDK reference:

  • REST via http or dio, WebSocket signaling via web_socket_channel, media via livekit_client, token storage via flutter_secure_storage.
  • Every endpoint, field, and message type is taken verbatim from contracts/openapi/* and contracts/ws-protocol/signaling.json.
  • The section opens with an admonition stating that no EthioConnect pub.dev package exists yet.

4. Native Dart SDK to follow ADR 0017​

A future Dart SDK will mirror the mobile SDK architecture: typed models, resource facades with the same naming as the JS SDK, a signaling connection implementing the disconnected -> connecting -> connected -> resuming lifecycle with session_id/last_seq resume, LiveKit as a regular dependency, and an async token-provider closure. When it ships, the integration guide pages become "under the hood" documentation rather than the primary path.

Update (2026-07-26): Shipped. The native SDK exists at sdks/dart/commbaas/ and is documented in ADR 0022 — Native Dart SDK (commbaas). The Flutter guide pages have been rewritten SDK-first, with the raw-contract material retained as "Under the hood" sections, exactly as planned here.

Consequences​

  • Positive: Flutter developers get accurate, contract-faithful documentation today instead of waiting for a native SDK.
  • Positive: A single product name across docs, portal, and onboarding removes the ambiguity of a category name doubling as a product name.
  • Positive: Keeping package identifiers unchanged avoids a breaking migration for existing SDK consumers.
  • Negative: Brand (EthioConnect) and package namespaces (comm-baas/CommBaaS) diverge, which will need explaining in onboarding materials. Accepted until a deliberate package-rename ADR.
  • Negative: The Flutter integration guide documents raw endpoints and wire messages, so any contract change must be propagated to it manually until the native Dart SDK exists. (Resolved by ADR 0022: contract changes are now absorbed by the SDK's typed models.)
  • Follow-up: The notification contract (contracts/openapi/notification.yaml) covers webhook subscriptions only; there is no device-token registration endpoint for mobile push. The Flutter docs document the webhook-plus-own-backend pattern; a first-party push registration API should be considered alongside the Dart SDK. (Still open — carried forward in ADR 0022.)
  • Follow-up (done — see ADR 0022): Author the native Dart SDK ADR (architecture per ADR 0017, package name, pub.dev publishing) when work begins.