ADR-0012: Profile-switched outbound gateways — local dev needs zero external credentials
Status: Accepted
Date: 2026-06-05
Scope: core (any backend talking to external services)
Context
Outbound integrations (email, payments, AI providers, …) tempt two bad setups:
requiring real credentials to boot a dev environment (slow onboarding, secrets
sprawl, accidental real side-effects from a laptop), or if (isDev) branches
inside business logic.
Decision
Every outbound integration is a port (interface) in the application layer
with at least two implementations, selected by Spring profile:
the real adapter under @Profile("!dev") — talks to the actual service;
a log/no-op adapter under @Profile("dev") — records the call (logs the
email body, fakes the response) so flows are fully exercisable locally.
Business logic depends only on the port; it cannot tell which adapter is
active. Example (Expenses): RawEmailGateway with SmtpEmailGateway
(@Profile("!dev")) and LogEmailGateway (@Profile("dev")) — local dev
needs no SMTP credentials, and registration emails print to the console.
Where behavior must differ more richly than swap-the-adapter (e.g. a sandbox
mode of the real service), prefer the service’s own test mode (Stripe test
keys) injected via environment config — still no code branches.
Consequences
git clone → run works with no secrets; onboarding is the BOOTSTRAP doc, not
a credentials scavenger hunt.
No accidental real-world side effects from development machines.
Each new integration costs one extra (trivial) dev adapter.
Amendment — 2026-09-10: required settings have no default in the base profile
The same split between profiles applies to the settings the app cannot run without: the
datasource, and secrets such as the JWT signing key.
The base profile reads them from environment variables with no default
(url: jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}). A deployment that forgets
one fails at startup, instead of reaching for localhost or a known key.
The dev profile supplies local defaults that match the compose file
(${DB_HOST:localhost}), so dev still needs zero configuration.
An optional integration may default to blank in the base profile, which leaves its
feature off. A credential never gets a working default there.
Evidence: both Expenses and dracomania follow this for the datasource, and Expenses also
for JWT_SECRET. One exception found: Expenses’ base application.yml defaults SWAGGER_USER / SWAGGER_PASSWORD, the Basic-auth credentials guarding its API docs.
Amendment — 2026-09-10: notifications are sent after commit
Mail is a side effect the database cannot roll back. Sent inside the use case’s
transaction, it can announce a change that then rolls back. And a mail failure becomes the
use case’s failure: the change it announced is undone, and the request answers 500. Both
backends met this and settled on the same shape.
A notification whose failure must not change the request’s outcome is sent after
commit.
The use case publishes an event, and a @TransactionalEventListener(phase = AFTER_COMMIT) sends the message. The use case knows nothing about mail, and a message
only goes out for a change that was saved.
Nothing about the send reaches the response. The listener either catches and logs its
own failure (Expenses), or runs @Async, so a failure lands in the async error handler
(dracomania).
Also @Async when the response must not wait on the mail server. On an endpoint that
must answer alike whether or not an account exists, a synchronous send would make a
registered address’s answer measurably slower than an unknown one’s.
Publish inside the transaction. With none active, a @TransactionalEventListener does
not run at all (unless it sets fallbackExecution = true), and nothing reports it.
A synchronous listener that writes to the database uses REQUIRES_NEW. The
publishing transaction has already completed, and a write that joins it is never
committed.
This covers fire-and-forget notifications. A call whose result the request needs, such as
creating a checkout session or asking a model, stays inline, and its failure is the
request’s failure.
Accepted: delivery is at most once. A mail lost after commit is not retried. In
dracomania the player asks again once the cooldown passes; Expenses records every attempt,
failed or not, in email_deliveries, where support can see it. A mail that must never be
lost needs an outbox.
An outbox meets this amendment too, and is the stronger option. Queuing the email as a row
in the business transaction means it commits only with the change, and a worker sends it
later, outside the request. So the failure never reaches the response, nothing waits on the
mail server, and a crash between commit and send loses nothing. Expenses moved every email to
one in backend v1.80.0 (expenses be/0029); there the after-commit listeners below are history.
Evidence: dracomania PasswordResetEmailSender (after commit, @Async). Expenses, until
backend v1.80.0: UserRegisteredEmailListener, PaymentFailedEmailListener and AccountDeletionEmailListener (after commit, catch and log), and from v1.74.0 PasswordResetEmailListener and VerificationEmailListener (after commit, @Async — the
forgot-password and resend endpoints are the ones that must answer alike for unknown
addresses); since v1.80.0 the same listeners queue through EmailOutbox inside the
transaction. Where a project does not yet comply is recorded in that project’s own docs.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
// LogEmailGateway.java@Profile("dev")public class LogEmailGateway implements RawEmailGateway { public void send(EmailMessage message) { log.info("[EMAIL] To: {} | Subject: {} | Body: {}", message.to(), message.subject(), message.body()); }}// SmtpEmailGateway.java@Profile("!dev")public class SmtpEmailGateway implements RawEmailGateway { // real SMTP, real credentials}
The pair is dev and !dev, not dev and prod — so exactly one implementation
exists in every profile, including profiles nobody has invented yet. A prod-only
annotation would leave a test or staging profile with no bean and a startup
failure, or worse, with the real gateway.
The point is that git clone && run works with zero credentials: a developer with no
SMTP password still sees the email in the log, in full. The same shape repeats for
Google Play (StubGooglePlayGateway / GooglePlayApiGateway).
The corollary the ADR records: a required setting has no default in the base profile.
A default is what lets a misconfigured production boot quietly and send nothing.
The 2026-09-10 amendment — the send happens after the commit.
@Component@RequiredArgsConstructorpublic class UserRegisteredEmailListener { private final EmailGateway emailGateway; @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT) public void onUserRegistered(UserRegisteredEvent event) { var user = event.user(); try { emailGateway.send(new EmailMessage( user.getEmail().value(), "Verify your email address", ..., EmailKind.WELCOME, user.getId())); } catch (Exception e) { log.error("Failed to send verification email to {}: {}", user.getEmail().value(), e.getMessage()); } }}
RegisterUserUseCase publishes UserRegisteredEvent and knows nothing about mail. The
listener runs after the commit, so no verification email can announce an account that then
rolled back.
The try/catch is the second half of the rule, and the easier half to leave out: without
it, a dead SMTP host would propagate out of the listener and turn a registration that is
already committed into a 500. The user would have an account and an error page. Catching
and logging keeps the failure where it belongs — in the logs, and in email_deliveries,
where support can find it.
Source: expenses · infrastructure/email/, as it was until backend v1.80.0 (EmailGateway is gone since)
Later, in Expenses: the send no longer happens in the listener at all. Every email is queued
in the business transaction and sent by an outbox worker (expenses be/0029), so the listener
neither waits on SMTP nor needs the try/catch, and the rollback concern above is met by the
transaction itself. The rule this amendment states — a mail failure must never undo or fail the
business change — still holds; an outbox is one way to meet it, and the stronger one when a crash
between commit and send must not lose the email.