Roadmap
The roadmap lives on GitHub. The umbrella issue is #62 Roadmap: from idle prototype to production-grade channel hub, and it is split into five epics. This page summarizes them and lists every issue with its state as of October 2026. GitHub is the source of truth: when an issue and this page disagree, the issue wins.
Vision
Converger connects communication channels to each other. Every channel is inbound, outbound or duplex. Messages are persisted once, ordered per conversation, and routed to any number of target channels with transformations, retries, receipts and full observability. WebSocket is the first-class channel, with its own documented protocol, and webhooks, WhatsApp, Telegram, Slack, Email, SMS and message brokers follow. The system scales horizontally, never loses an acknowledged message, and should be easy to integrate with.
| Phase | Epic | Focus | Status |
|---|---|---|---|
| 1 | #57 v2.5 Production Hardening | No data loss, security baseline, CI | Done |
| 2 | #58 v3.0 WebSocket-first & Converger Protocol v1 | Duplex WS adapter, acks, receipts, spec, one socket stack | Done; the 10k-socket rolling-restart measurement is #190 |
| 3 | #59 v3.1 Scale & Reliability | Clustering, partitioning, breakers, DLQ, SLO telemetry | Done |
| 4 | #60 v3.2 Channel Expansion | Adapter v2, conditional routing, new channels | Done |
| 5 | #61 v3.3 Developer Experience | OpenAPI, SDKs, docs, management API, UI | Done |
All five phases are done, and the roadmap (#62) is closed. The exit-criteria measurements were made (#190, #191, #192) and the follow-ups they found fixed (#198, ADR-0076, ADR-0077). The SDKs are on npm, PyPI, NuGet, Hex and the Go module proxy, released from CI (Releasing the SDKs).
Done: v2.5 Production Hardening (#57)
The hardening epic is closed. The goal was that no message can be lost, no tenant can read another tenant's secrets, and the hot paths are bounded. The decisions behind these fixes are recorded as ADRs.
Data loss
| Issue | What changed |
|---|---|
| #1 | Delivery jobs are enqueued in the activity's transaction (transactional outbox, ADR-0001). |
| #2 | The Broadway backend no longer drops failed deliveries: retries and dead letters go through Oban (ADR-0002). |
| #3 | The WebSocket new_activity path no longer double-delivers or bypasses the pipeline (ADR-0003). |
| #15 | The WhatsApp adapters parse every message and status in a webhook batch (ADR-0015). |
| #19 | Per-channel retry policy, consistent with Oban, plus unique jobs and Lifeline (ADR-0019). |
Real-time contract and correctness
| Issue | What changed |
|---|---|
| #4 | The PubSub broadcast carries the full canonical activity (ADR-0004). |
| #5 | Clients can no longer set inserted_at, idempotency_key or other server fields (ADR-0005). |
| #6 | Monotonic per-conversation seq and opaque watermarks (ADR-0006). |
| #8 | Middleware receives the channel, and middleware crashes are contained (ADR-0008). |
| #18 | Every list query is bounded and keyset-paginated (ADR-0018). |
| #20 | Socket ids are per end user or conversation, not per channel (ADR-0020). |
Security baseline
| Issue | What changed |
|---|---|
| #9 | Inbound signature verification with per-channel enforcement, including /status (ADR-0009). |
| #10 | CORS_ORIGINS and the OpenTelemetry endpoint are read at runtime (ADR-0010). |
| #11 | The admin IP allowlist is proxy-aware through TRUSTED_PROXIES (ADR-0011). |
| #12 | Channel secrets and configs are encrypted at rest, API keys are hashed, and audit logs are redacted (ADR-0012). |
| #13 | Rate limiting on the hot paths, cluster-wide when clustered (ADR-0013). |
| #14 | Webhook hardening: SSRF guard, outbound signing, timeouts and response limits (ADR-0014). |
| #55 | Deployment hardening: no committed secrets, FORCE_SSL/HSTS, migrations as a separate step, backups, runbook (ADR-0022). |
Product gaps
| Issue | What changed |
|---|---|
| #7 | Uploaded files are served through an authenticated endpoint, with S3, GCS and Azure storage (ADR-0007, storage). |
| #16 | Participant-based conversation resolution for inbound messages (ADR-0016). |
| #17 | Conversation lifecycle (close, reopen, expiry) enforced under the seq lock (ADR-0017). |
Tooling
| Issue | What changed |
|---|---|
| #54 | CI with format, warnings-as-errors, Credo, Dialyzer, Sobelow, dependency audit, tests on Postgres and coverage (ADR-0021). |
| #56 | Dependency and platform upgrades: LiveView, Hammer 7, Graph API version, Oban Web, OTEL config, Elixir/OTP alignment (ADR-0023). |
The exit criterion was a chaos test: killing a node under load loses no acknowledged message across REST and WebSocket. See Chaos testing.
Done: v3.0 WebSocket-first & Converger Protocol v1 (#58)
WebSocket becomes the primary channel, with a documented wire protocol that any language can implement. A WebSocket channel can be the source or target of routing rules, delivers with acks, resumes exactly from a watermark, and exposes receipts, typing and presence. The two existing socket stacks collapse into one. The design principles: persist first, then push; client ids plus acks give at-least-once send with exactly-once persistence; the protocol comes before the SDKs; and everything is bounded.
| Issue | Title | State |
|---|---|---|
| #63 | Converger Protocol v1 must be wire-compatible with mekik/1 (hello/welcome, seq envelope, chativa frame vocabulary) | Done (Protocol v1, ADR-0024, ADR-0068) |
| #21 | Specify the Converger Protocol v1 (WebSocket wire protocol) | Done (Protocol v1, Message vocabulary) |
| #22 | Make websocket a first-class duplex channel adapter (deliver to sockets, offline buffering, fan-out target) | Done (WebSocket channel, ADR-0033) |
| #23 | Unify UserSocket/ConversationChannel and ConvergerSocket/ConvergerChannel into one protocol implementation | Done (ADR-0026) |
| #24 | Client-side message ids with server acks over WebSocket (at-least-once send, exactly-once persistence) | Done (ADR-0029) |
| #25 | Push delivery/read receipts, typing indicators and presence to WebSocket clients | Done (ADR-0032) |
| #26 | Raw WebSocket endpoint (non-Phoenix framing), optional MessagePack encoding, and SSE/long-poll fallback | Done (ADR-0030, ADR-0035) |
| #27 | WebSocket connection limits, backpressure, socket draining and graceful shutdown | Done (WebSocket limits, ADR-0027) |
| #28 | Rich activity model: activity types, attachment schema, reactions, edits/deletes, reply threading | Done (ADR-0036) |
| #68 | Rich message vocabulary compatible with chativa: buttons, quick-reply, cards, carousel, image/file, GenUI and tool traces as first-class activity payloads with per-channel downgrade | Done (Message vocabulary, ADR-0062, ADR-0064) |
| #64 | mekik integration: agent-side multiplexed socket, mekik channel adapter, and seq authority between Converger and mekik | Done (mekik channel, ADR-0063, ADR-0066) |
| #65 | Chativa as the reference WebSocket client: verify connector-mekik against Converger, add hub extras (delivery status, upload, history, multi-conversation) | Done (Converger side, ADR-0065; the client side is open in chativa#86) |
| #67 | Agent SDK and bot-side adapters: channel-scoped agent sockets, @converger/agent SDKs in several languages, first-party LangServe/LangChain and mekik adapters | Done (Agent SDKs, ADR-0067, ADR-0069); the first npm and PyPI release is #187 |
| #190 | Measure a rolling restart with 10 000 WebSocket connections (zero acked loss) | Done (2026-10-15 run; reconnect fixed in #198, after #198) |
Suggested order: #63 and #68 feed the spec, then #21, then #22 with #23, #24, #25, #27, #28, and finally #26. Exit criteria: a WhatsApp to WebSocket agent console bridge works end to end with receipts; a Python client written only from the spec passes the conformance suite; a rolling restart under 10k connections loses no acknowledged message.
Done: v3.1 Scale & Reliability (#59)
Run Converger as a cluster that meets the PRD targets (10M messages per day, 1k+ concurrent sockets per node, p95 below 250 ms end to end), and keep it healthy when a provider or the database misbehaves.
| Issue | Title | State |
|---|---|---|
| #29 | Multi-node clustering: libcluster strategies, cross-node verification, health/readiness endpoints, k8s manifests | Done (k8s manifests validated statically, not yet against a live cluster) |
| #33 | Delivery and pipeline telemetry, Grafana dashboards and alert rules (SLO instrumentation) | Done |
| #31 | Per-channel circuit breaker, provider rate limiting and tenant-fair queueing | Done |
| #32 | Dead-letter queue with inspection and replay (API + admin UI) | Done |
| #30 | Table partitioning and retention for activities and deliveries; archival to object storage | Done (Retention, ADR-0034) |
| #35 | Graceful degradation under database pressure: pool sizing, timeouts, bulkheads, readiness flip | Done (ADR-0044) |
| #66 | Pluggable event backbone: Elixir-native (PubSub + Oban) by default, Kafka/NATS/RabbitMQ selectable, with a published benchmark matrix | Done, see Event backbone and Backbone matrix |
| #34 | Load testing harness (k6 WebSocket + REST scenarios) with nightly CI run and published baselines | Done (Kafka column with #66; full re-run after #35), see Benchmarks |
| #191 | Measure dead-channel isolation: one dead channel must not degrade other tenants | Done (ADR-0076, Dead-channel isolation) |
| #192 | Verify partition archive and drop on a 100M-row dataset | Done (2026-10-15 run) |
Exit criteria: a nightly load test publishes p95 latency and connection counts with enforced thresholds; one dead channel does not degrade other tenants; partition drop and archive are verified on a 100M-row dataset.
| Exit criterion | Status |
|---|---|
| Nightly load test with p95 and connection counts, thresholds enforced | See Benchmarks (nightly Load workflow) |
| One dead channel does not degrade other tenants | Mostly met since ADR-0076 (#191): with a 10,000-delivery backlog on a dead channel in the same tier, the other tenant's p95 is 104 ms against a 67 ms baseline (it was 12.3 s before); a second, noisier run measured 535 ms, so the strict gate is not yet reliably met. See Dead-channel isolation. |
| Partition drop and archive verified on 100M rows | Met: measured on a 100M-row dataset (2026-10-15 run, #192): detach 205 ms, drop 14 ms, writers not blocked, the 16.7M-row month archived and verified in 530 s. The 10M and 30M runs per table and the per-table 100M extrapolation are in Partition retention at scale. |
Done: v3.2 Channel Expansion (#60)
Turn the adapter layer into a real plugin system and ship the channels integrators ask for most. Conditional routing with reply-back makes multi-channel conversations usable.
| Issue | Title | State |
|---|---|---|
| #36 | Adapter behaviour v2: capabilities/0, config_schema/0, provider signature verification, typing, health probe | Done (Writing an adapter, ADR-0038) |
| #43 | Conditional routing rules: filters, priority, reply-back routing, per-rule transformations, dry-run | Done (Routing rules, ADR-0046) |
| #37 | WhatsApp: media messages, template (HSM) messages, interactive messages and inbound media download | Done (WhatsApp, ADR-0039) |
| #38 | Telegram Bot adapter (duplex) | Done (Telegram, ADR-0041) |
| #39 | Slack adapter (Events API inbound, Web API outbound, signing secret verification) | Done (Slack, ADR-0040) |
| #40 | Email adapter (outbound via Swoosh, inbound via provider parse webhooks) | Done (Email, ADR-0042) |
| #41 | SMS adapters (Twilio, Vonage) with delivery receipts | Done (SMS, ADR-0045) |
| #42 | Message broker channel adapters: Kafka, RabbitMQ, NATS, Redis Streams as first-class channels | Done (Broker channels: Kafka, RabbitMQ, NATS JetStream, Redis Streams; ADR-0047, ADR-0054) |
| #44 | Backlog of additional adapters: Discord, Microsoft Teams (Bot Framework), Facebook Messenger, Instagram, Viber, MQTT, gRPC streaming | Done: Discord, Teams, Messenger, Instagram, Viber and HTTP pull (Channels, ADR-0048); MQTT and Discord Gateway inbound (MQTT, Discord, ADR-0055); gRPC streaming (Protocol v1 over gRPC, ADR-0056) |
Exit criteria: adding an adapter touches only the adapter module and one config line, and at least three new duplex channels reach production quality with fixture-based tests. Adapter requests go to #44.
Done: v3.3 Developer Experience (#61)
Make Converger adoptable by someone who has never read its source: a license, a five-minute getting-started, an OpenAPI spec with a playground, typed SDKs with reconnect built in, a management API, event webhooks, and a modern admin and portal UI.
| Issue | Title | State |
|---|---|---|
| #48 | Documentation site and OSS hygiene: guides, adapter authoring, deployment, LICENSE, CONTRIBUTING, SECURITY, templates, CHANGELOG | Done (this site, ADR-0025, ADR-0073) |
| #45 | OpenAPI 3.1 specification, Swagger UI, consistent error envelope and API versioning policy | Done (OpenAPI, ADR-0050) |
| #46 | TypeScript SDK (@converger/client) implementing Protocol v1 with reconnect, watermark resume, outbox and token refresh | Done (TypeScript SDK, ADR-0051) |
| #47 | Server-side SDKs: Python and Go (REST + WebSocket), Elixir client library, signature verification helpers | Done (Server-side SDKs, ADR-0052) |
| #51 | Management API: tenants, channels, routing rules, users and secret rotation via REST with scoped API keys | Done (Management API, ADR-0061) |
| #52 | Auth hardening: token revocation, refresh rotation, scoped tokens, admin 2FA, password reset, session expiry | Done (Client tokens, Security model, ADR-0058, ADR-0059) |
| #49 | Platform event webhooks: tenant-level subscriptions for activity, delivery, conversation and channel events (signed, retried) | Done (Platform event webhooks, ADR-0053) |
| #50 | Admin panel and tenant portal modernization: Tailwind/daisyUI, pagination and search, channel test-send, key rotation, deliveries view, live tail | Done (Admin panel and tenant portal, ADR-0060) |
| #53 | Windows developer setup: bcrypt_elixir requires MSVC nmake; document or offer a pure-Elixir hashing option | Done (Getting started, dev container, ADR-0057) |
| #187 | First release of the SDK packages to npm and PyPI (manual, last on the roadmap) | Done: 0.1.0 of every SDK published by hand |
| #188 | Publish SDK releases from CI: npm token/OIDC and PyPI trusted publisher | Done: every SDK released 0.1.1 from CI (Releasing the SDKs) |
Exit criteria: a new integrator provisions a tenant and a channel through the API, embeds the TypeScript SDK and exchanges messages using only the docs; the docs site is published from CI; the GitHub community profile is complete.
How to contribute
Pick an unassigned issue in the current epic, comment to claim it, read the contributing guide, and run mix precommit before opening a pull request. Changes that alter behavior update the docs in the same pull request (ADR-0025).