ADR-0053: Better Auth owns users in Bun — no users hexagon
Status
Accepted (2026-07-25)Tags
authentication, better-auth, bun, architecture, hexagonal, ddd, users, dead-code, adr-0006Decision
The Bun backend does not model users as a domain. There is noUserRepository, no
UserRepositoryPort, and no user use-cases. Better Auth owns the users table, password
hashing, email verification, and sessions.
Route handlers reach user operations through container.authPort (the AuthPort seam) or
Better Auth’s own API. packages/users-domain/ deliberately holds only the Zod schemas
that validate the users HTTP surface — no entity, no errors, no repositories, no ports, no
use cases. It is a validation package, not a domain.
Better Auth’s core user fields — name, image, email, password, emailVerified,
ban state — are written through Better Auth, never by direct SQL. For a write that has a
Better Auth session, use its /update-user endpoint; for a server-side write scoped to a
user id (this API also serves JWT-only mobile callers, which have no Better Auth session),
use (await container.auth.$context).internalAdapter.updateUser(userId, …). Both paths fire
the configured databaseHooks.user.update hooks and refresh cached sessions.
Direct column writes to schema.user are permitted only for Gremlin-invented columns
that Better Auth does not know about — currently just language_preference — and only from
the route layer.
This is a deliberate, scoped exception to the general Hexagonal + DDD rule in
backend/bun/AGENTS.md, not a repudiation of it. The other packages remain properly
layered; AuthPort is the reference hexagon.
Why
Better Auth already provides everything a users hexagon would wrap. A port + repository on top of it adds a layer that holds no behaviour of its own — the interface would be as complex as the implementation, with nothing gained. This is not a theoretical concern. The hexagon was built, then abandoned in place, and the residue survived for months:- Four use-case classes whose only body was
throw new Error('... delegated to Better Auth API'). They were not even exported from the package’sindex.ts, so nothing could call them. createUserServices()returned{}from an emptyUserServicesinterface — yet was still invoked on every application boot, and its empty result handed to aassignServices()helper that existed solely to receive it.- A 169-line
user.repository.port.spec.tsdocumenting a MongoDB repository withClientSessionandmongoClientexamples. This project uses PostgreSQL, and the interface it described (IUserRepository) never existed. - A spurious
mongodb: 7.1.1dependency declared by a package containing zero MongoDB code. - A
Useraggregate root — exported, referenced by nothing — carryingpasswordHash,changePassword(),activate()/deactivate(), and a default['customer']role array. Every one of those responsibilities belongs to Better Auth, and none of that state was ever read. ThreeLocalizedErrorsubclasses (DuplicateEmailError,InvalidCredentialsError,UserNotFoundError) had likewise never been thrown.
commands/,
queries/, ports/, di/ — lied convincingly. It made both humans and coding agents
conclude that user logic lived there. During the architecture review that produced this
ADR, the first recommendation generated was “the handler is bypassing its domain package,
wire it through the existing ports” — a suggestion that was impossible to act on, because
there were no working ports behind the facade. Dead code that merely sits there is cheap;
dead code that generates confident wrong advice is not.
The fossil survived precisely because AGENTS.md used the user domain as its worked
example of hexagonal architecture, in five separate places (UserRepositoryPort,
UserRepository, CreateUserUseCase, user-repository.port.ts, and a code sample that
inserted directly into schema.user). The documentation kept re-legitimising the thing the
code had abandoned. That is why this ADR is paired with an AGENTS.md rewrite — an ADR
alone would not have stopped it, because agents read AGENTS.md far more often than
docs/adr/.
Relationship to ADR-0006
Complementary, covering the two sides of the same boundary:
Neither stack builds its own user persistence layer. Better Auth is the single source of
truth for identity.
Consequences
- Adding a user-related feature means extending a route handler plus, where relevant, the DTO schema — not adding a layer.
- Profile fields Gremlin invents (like
language_preference) live as columns on the Better Authuserstable and are written directly. This is accepted coupling, chosen over maintaining a parallel profile table. - If Better Auth is ever replaced, the blast radius is the route handlers plus
packages/auth-adapter/. That is the trade accepted here:AuthPortalready provides the seam for swapping the auth provider, so a second users-layer would be redundant insurance.
Rules for agents
- Never create
UserRepository,UserRepositoryPort, or user use-cases inbackend/bun. - Never
INSERTintoschema.userto create a user — sign-up goes throughcontainer.authPort.signUp.email(...). - Never
UPDATEa Better Auth core field (name,image,email, password,emailVerified, ban state) with direct SQL — it skips thedatabaseHooks.user.updatehooks and leaves cached sessions stale. UseinternalAdapter.updateUser. - Direct
UPDATEonschema.useris allowed only for Gremlin-invented columns — currently justlanguage_preference— from the route layer. - A profile-write endpoint must persist and then return the stored row, never echo the request body back. See the bad pattern below.
- When you need a hexagonal example to copy, use
AuthPort(packages/auth-ports/ports/auth.port.ts→packages/auth-adapter/better-auth.adapter.ts), never users.