Communication Service — Backlog & Scorecard

Last updated: 2026-07-04 (Flows modernization + full revamp shipped) Analyst: Codebase audit (full source + spec + test review)

⚠️ Much of the original backlog below is now RESOLVED. The service was made a full Vlozi Flows citizen and then went through a 4-phase revamp (correctness → hardening → deliverability → quality). See Revamp Status immediately below for what's fixed vs. still open before reading the (historical) Bugs / Areas of Improvement sections.

Revamp Status (2026-07)

Flows modernization (69b2b99): comms emits comms.email.sent/failed/delivered/ bounced/complained + comms.alias.claimed; exposes comms.* MCP tools (send_message, claim_alias, list_logs, get_analytics, check_alias_availability, get/update_sender_settings) + 6 trigger descriptors; on the mcp-gateway.

Revamp — Phase 1 correctness (4272f73), Phase 2 hardening (d86b05d), Phase 3 deliverability (5d55bf8), Phase 4 quality:

Still open / deferred: full self-serve domain verification (Resend Domains API + tenant_sending_domains), real SMS/WhatsApp + multi-provider/BYOP, batch + scheduled sends, audit log (A5), DLQ (queue-limit-blocked), List-Unsubscribe defaulting (needs a routed unsubscribe mailbox), the fuller index.ts routes/services split (pure leaf modules lib/resend.ts + lib/svix.ts + lib/text.ts are extracted).

Scorecard

Overall: 7.5 / 10

Bugs

B1 — Unverified fromEmail silently fails at Resend with no user explanation

Severity: High Location: src/index.ts → dispatchSend(), PUT /v1/sender-settings

The fromEmail field accepts any value via PUT /v1/sender-settings (no verification step). When this address is used in a send, Resend returns a 403 "domain not verified" response. The service logs the error, marks the message failed, and returns a 500 to the caller — but no user-facing explanation distinguishes "domain not verified" from "network error". Users who configure fromEmail and then see failed sends have no visibility into the actual cause.

B2 — No retry logic: transient Resend failures permanently fail the message

Severity: High Location: src/index.ts → sendViaResend()

A single Resend API call attempt is made. Any network error, timeout, or Resend 5xx immediately marks the message status: "failed" with no retry. There is no queue, no exponential backoff, no dead-letter path. Transient failures (Resend degraded, Worker CPU timeout) are permanent from the caller's perspective.

B3 — Webhook replay creates duplicate messageEvents and double-counts engagement

Severity: Medium Location: src/index.ts → POST /v1/webhooks/resend

Svix replays failed webhook deliveries automatically. Each replay results in a new row in comms_message_events and a second call to NEWSLETTER_SERVICE /internal/event. There is no deduplication on (message_id, status) before insert. An email that is "delivered" and then the webhook is replayed → newsletter sees two engagement events for the same send, inflating opens/clicks metrics.

B4 — messageEvents has no FK to messageLogs (documented as "not enforced")

Severity: Low Location: src/db/schema.ts, migration 0000_warm_winter_soldier.sql

comms_message_events.message_id references comms_message_logs.id in intent but not via DB constraint. A webhook for an unknown or deleted providerMessageId inserts silently. No orphan cleanup, no alert. Over time the events table can accumulate orphan rows that degrade query performance and confuse log viewers.

B5 — SMS channel returns status: "sent" but never sends anything

Severity: Medium (feature is deceptive) Location: src/index.ts → dispatchSend() SMS branch

When channel: "sms" is posted, the service logs to console and marks status: "sent". No Twilio call is made. The billing accumulator is NOT charged (accumulator only runs for email), but the call returns 200 OK. Callers (e.g., notification triggers from CI) believe the SMS was delivered. No error is surfaced.

B6 — senderEmail not validated as a syntactically valid email

Severity: Low Location: src/index.ts → PUT /v1/sender-settings

The Zod schema for sender_email uses z.string().optional() — no .email() validator. A tenant can store "not an email at all" as their reply-to. Resend may silently strip or reject the reply_to header, causing customer replies to bounce.

B7 — DB handle cached by URL only — shared handle if two env vars collide

Severity: Low Location: src/db/client.ts

The drizzle client cache key is COMMS_DATABASE_URL. If a misconfigured deployment sets two workers' COMMS_DATABASE_URL to the same string (e.g., a copy-paste error), they share a drizzle instance within the same Worker isolate. In tests, each test calls freshEnv() to bust the cache — production has no equivalent guard.

B8 — Alias check-then-claim is non-atomic; 409 on race not documented in dashboard UX

Severity: Low Location: src/index.ts → GET /v1/aliases/availability, POST /v1/aliases/claim

The availability check and claim are two separate requests with a window between them. Another tenant can claim the slug after the check returns available: true but before the claim is submitted. The race is handled correctly at the DB level (unique constraint → 409 + credit refund), but the 409 is not documented as a possible response in the dashboard UI — users may see an unhandled error state.

Areas of Improvement

A1 — Rate limiting absent on /v1/send

A tenant can POST /v1/send in a tight loop, exhausting the Worker's Resend quota and incurring large credit bills (or hammering the billing accumulator). Native Cloudflare rate limiting (ratelimit binding) should be added with a per-tenant budget (e.g., 60 sends/min).

A2 — Implement exponential backoff + DLQ for Resend failures

Network errors and Resend 5xx responses should be retried with 1s/5s/15s delays via Cloudflare Queues. After 3 attempts, move to DLQ and mark the log status: "failed". This matches the pattern used in content-engine and newsletter services.

A3 — Domain verification flow missing

fromEmail is stored but there is no guided verification flow. The service should expose a POST /v1/sender-settings/verify-domain that calls the Resend domain verification API and surfaces the DNS records the tenant must add. Without this, fromEmail is a footgun.

A4 — Add messageEvents deduplication (idempotency on webhook)

Before inserting into comms_message_events, check if (message_id, status) already exists. Skip insert and newsletter fan-out if so. This makes webhook processing idempotent against Svix retries.

A5 — Add audit log for sensitive operations

Alias release and sender settings changes have no audit trail. A comms_audit_log table with (tenantId, action, actorId, payload, timestamp) rows would allow support to trace who changed what and when — especially important for "my alias was released and claimed by someone else" disputes.

A6 — Enrich /v1/logs with delivery event data

The current /v1/logs response shows the initial send status but not subsequent delivery events (delivered, bounced, opened). The UI has no way to show "email delivered at 10:05am". A JOIN or sub-select from comms_message_events would make the log view much more useful.

A7 — Implement Twilio for SMS

The SMS code path is a console stub. Either implement Twilio with the existing architecture (apiKey in env, same dispatchSend structure) or return 501 Not Implemented clearly so callers don't believe SMS was delivered.

Feature Completeness vs Spec