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-0006

Decision

The Bun backend does not model users as a domain. There is no UserRepository, 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’s index.ts, so nothing could call them.
  • createUserServices() returned {} from an empty UserServices interface — yet was still invoked on every application boot, and its empty result handed to a assignServices() helper that existed solely to receive it.
  • A 169-line user.repository.port.spec.ts documenting a MongoDB repository with ClientSession and mongoClient examples. This project uses PostgreSQL, and the interface it described (IUserRepository) never existed.
  • A spurious mongodb: 7.1.1 dependency declared by a package containing zero MongoDB code.
  • A User aggregate root — exported, referenced by nothing — carrying passwordHash, 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. Three LocalizedError subclasses (DuplicateEmailError, InvalidCredentialsError, UserNotFoundError) had likewise never been thrown.
The real cost was not the dead lines. It was that the shape of the folders — 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 Auth users table 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: AuthPort already 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 in backend/bun.
  • Never INSERT into schema.user to create a user — sign-up goes through container.authPort.signUp.email(...).
  • Never UPDATE a Better Auth core field (name, image, email, password, emailVerified, ban state) with direct SQL — it skips the databaseHooks.user.update hooks and leaves cached sessions stale. Use internalAdapter.updateUser.
  • Direct UPDATE on schema.user is allowed only for Gremlin-invented columns — currently just language_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.

Bad pattern (do not generate)

Good pattern