Hexagonal architecture for real, not in theory

On the Wakfuli backend, most business modules (items, folders, actions, auth, havenbag, builds, skinator, sublimations) avoid this trap with the same recurring split: domain/, application/ (the ports), adapters/, services/, controllers/, presenters/, validators/. This isn't ceremony bolted on after the fact, it's the default folder structure of a module. The spells module, on the other hand, has neither application/ nor adapters/: it exposes read-only reference data, with no business rule to isolate, and nobody forced the mold onto it. That detail matters: the discipline here isn't dogmatic, it applies where there's a boundary worth defending.

A port and its adapter, not an abstract promise

Take the skinator module, which handles character skin creation. skinator/application/ports.ts defines the interface the domain expects from a skin repository, with no knowledge of Lucid or Postgres:

export interface SkinRepository {
  findByUuidAndUser(uuid: string, userId: number): Promise<Skin | null>;
  findByUuid(uuid: string): Promise<Skin | null>;
  create(data: CreateSkinData): Promise<Skin>;
  mergeAndSave(skin: Skin, data: UpdateSkinData): Promise<Skin>;
  delete(skin: Skin): Promise<void>;
  getUserSkins(userId: number, page: number, limit: number, filters?: SkinFilters): Promise<ModelPaginatorContract<Skin>>;
  getPublicSkins(page: number, limit: number, filters?: SkinFilters): Promise<ModelPaginatorContract<Skin>>;
}

skinator/adapters/skin_repository_adonis.ts implements this interface with Lucid, SQL queries included:

export class AdonisSkinRepository implements SkinRepository { 
  async findByUuid(uuid: string): Promise<Skin | null> {
    return Skin.query().where('uuid', uuid).first();
  }
 
  async create(data: CreateSkinData): Promise<Skin> {
    return Skin.create({
      userId: data.userId ?? null,
      name: data.name.trim(),
      breedId: data.breedId,
      // ...
    });
  }
  // mergeAndSave, delete, getUserSkins, getPublicSkins follow the same pattern
}

Where it really costs you, and where it cheats a little

This is where honesty starts. The domain isn't as pure as the folder structure suggests. skinator/domain/skin.ts, supposedly the business entity, is actually a Lucid model: it extends BaseModel, carries @column decorators, knows its table name. It's not a business object decoupled from persistence in the strict DDD sense, it's an Active Record. What the port isolates isn't the shape of the entity, it's how you access it: the queries, the filters, the pagination. The hexagonal boundary here protects data access, not the entity itself. It's a deliberate compromise, not textbook hexagonal, and that's better than a hollow port pretending otherwise.

A second, subtler nuance: SkinsService declares its constructor with private readonly repo: AdonisSkinRepository, the concrete class, not SkinRepository, the interface. The reason is pragmatic: AdonisJS's IoC container automatically resolves concrete classes marked @inject(), with no explicit binding to register for an abstract type. The port exists, the class honors it, the shared types (SkinFilters, CreateSkinData) do come from ports.ts.

What it buys you anyway

What this split makes possible, concretely:

The cost, though, is real and shouldn't be glossed over: nine modules with this split means dozens of small files for operations that, in a more direct style, would fit in a single controller class. On this backend, the application code as a whole runs past Révéler lines spread across these layers, for a medium-sized product. Part of that volume is structural: an interface that repeats the signatures of its implementation, a presenter that reformats what the service just computed. It's the kind of detail that makes some people say hexagonal, below a certain team or domain size, looks like folder theater: form without function, layers you pass through without them protecting anything, because nobody enforces them over time.

Here, what avoids that trap isn't the presence of the application/ and adapters/ folders, it's that they're actually traversed the right way: no controller touches Lucid, no service imports a model outside its own module without going through a repository, and the module that doesn't need the split (spells) simply wasn't given it. The discipline is verified by grepping, not by reading folder names.