Skip to content

ADR-0013: External providers behind adapters, with a simulator

  • Status: Accepted
  • Date: 2026-11-13

Messaging and scheduling depend on outside services: an SMS provider, an email provider and the calendars of recruiters. Development, automated tests and demos must run without a paid account, without secrets and without network calls. A provider must also be replaceable without touching the rules of ADR-0012.

How does the system talk to external providers?

  • The whole product flow runs locally with no account.
  • Changing provider means writing one adapter.
  • A provider never decides whether a message may leave.
  • The user can see on the screen when messages are simulated.
  1. One adapter interface per capability, selected by configuration, with a simulator as the default.
  2. Calls to the provider SDK from the features that need it. Obvious alternative, listed for comparison.
  3. Sandbox accounts of the real providers in development and tests. Obvious alternative, rejected: the automated suite makes no network call to the outside.

Chosen option: 1.

  • SMS: the interface SmsProvider, with simulator (default) and twilio, chosen by SMS_PROVIDER.
  • Email: the interface EmailProvider, with outbox (default, keeps the email locally instead of sending it), smtp and ses, chosen by EMAIL_PROVIDER. With smtp there is no receiving: replies go to the reply address the company registered, and the conversation says so. With ses the system also receives replies, bounces and complaints.
  • Calendars: a gateway with implementations for Google Calendar and Microsoft Graph, and a fake one for tests, chosen by CALENDAR_ADAPTERS. The fake is refused in production.

An adapter only carries a message and translates the format of its provider. It applies no sending rule and, with one exception, does not read or write the database. The exception is in the Twilio adapter (providers/twilio/twilio-opt-out.ts): when Twilio refuses a message because the phone opted out with the provider itself, the adapter records the withdrawal of consent, so the next send is refused by the sending service. The API does not start when a real provider is selected and one of its settings is missing. A webhook of a provider is accepted only after its signature is verified. With the simulator, the Messaging tab of Platform > Integrations shows “Simulator mode: messages are not delivered to real phones.”

  • Good, because the end-to-end tests cover sending, delivery status, replies and opt-out with no external dependency.
  • Good, because the sending service does not know the provider: the three email implementations sit behind the same interface and are chosen by configuration.
  • Bad, because the automated tests exercise the real adapters with recorded requests and local test servers, not with the live services. The first use with a live account needs its own verification.
  • Bad, because the interface is the common denominator of the providers: no MMS, and no inbound email with smtp.
  • apps/api/src/modules/platform-messaging/providers.ts: the interfaces.
  • apps/api/src/modules/platform-messaging/providers/ and simulator.ts: the adapters and the simulator.
  • apps/api/src/modules/platform/calendar/: the calendar gateways.
  • apps/api/src/core/config/config.ts: the selection variables and the start-up checks.
  • Concept pages: Messaging, Testing. Context and scope lists each external system as “In use”, “Simulator” or “Planned”.
  • User guide: Messaging settings, Calendars.