ADR-0013: External providers behind adapters, with a simulator
- Status: Accepted
- Date: 2026-11-13
Context and problem statement
Section titled “Context and problem statement”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?
Decision drivers
Section titled “Decision drivers”- 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.
Considered options
Section titled “Considered options”- One adapter interface per capability, selected by configuration, with a simulator as the default.
- Calls to the provider SDK from the features that need it. Obvious alternative, listed for comparison.
- Sandbox accounts of the real providers in development and tests. Obvious alternative, rejected: the automated suite makes no network call to the outside.
Decision outcome
Section titled “Decision outcome”Chosen option: 1.
- SMS: the interface
SmsProvider, withsimulator(default) andtwilio, chosen bySMS_PROVIDER. - Email: the interface
EmailProvider, withoutbox(default, keeps the email locally instead of sending it),smtpandses, chosen byEMAIL_PROVIDER. Withsmtpthere is no receiving: replies go to the reply address the company registered, and the conversation says so. Withsesthe 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.”
Consequences
Section titled “Consequences”- 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.
More information
Section titled “More information”apps/api/src/modules/platform-messaging/providers.ts: the interfaces.apps/api/src/modules/platform-messaging/providers/andsimulator.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.