Modules

Module Organization

The Bun Core Platform uses a layered module architecture with three main layers:

Apps — Entry points and orchestration
Packages — Shared code (domain, application, infrastructure)
Config — Centralized configuration

Apps Layer

`apps/monolith/`

The main Hono application. Wires together:

Server setup (Hono)
Middleware registration (rate limiting, idempotency, i18n, logging)
Route mounting (/api/v1/...)
DI container setup

apps/monolith/
└── src/
    ├── index.ts              ← App bootstrap
    ├── config/
    │   └── di-container.ts   ← Dependency injection
    ├── api-gateway/
    │   ├── middleware/       ← Global middleware
    │   ├── routes/           ← REST endpoint handlers
    │   └── errors/           ← Custom error classes
    └── modules/              ← Feature modules (gateway, etc.)

Packages Layer

This page used to list packages/domain/, packages/application/ and a modules/gateway/ tree. None of them exist. The domain/application split was never built here, and the gateway module is ClawUI, which is KIV (ADR-0053 removed the parallel attempt in users-domain). What follows is the real layout.

`packages/auth-ports/` and `packages/auth-adapter/`

The one live hexagon, and the arrangement to copy for a new seam.

packages/
├── auth-ports/
│   └── ports/
│       └── auth.port.ts        ← the AuthPort interface, and nothing else
└── auth-adapter/
    ├── better-auth.adapter.ts  ← AuthAdapter implements AuthPort
    └── schema.ts               ← the Drizzle schema Better Auth owns

Rules:

A port imports no library. auth.port.ts names no Better Auth type.
The adapter is the only file that does, and it translates library errors into @bun-core/shared-kernel ones at the boundary — see Ports & Adapters.
There is no entity, repository or use case between them. Add a layer when something calls it.

`packages/infrastructure/`

Adapters and infrastructure services, each behind a port where one exists.

packages/infrastructure/
├── database/
│   ├── repositories/           ← CustomRolesRepository (Drizzle/PostgreSQL)
│   └── mongodb.client.ts       ← log transport only, NOT persistence
├── cache/
│   ├── cache.port.ts           ← ICache
│   ├── bun-redis.cache.ts      ← BunRedisCache
│   └── in-memory.cache.ts      ← InMemoryCache fallback
├── events/
│   ├── event-bus.port.ts       ← IEventBus
│   └── in-memory.event-bus.ts
├── localization/               ← I18nService + translation JSON
└── logging/                    ← SmartLogger + Console/File/MongoDB transports

`packages/shared-kernel/`

ApplicationError and its subclasses (UnauthorizedError, ConflictError, …), the state machine, and shared types. Depends only on zod (for ValidationError) and ulid — no framework or infrastructure. This is what an adapter is required to throw, so error.middleware.ts can map it to a status code — AuthAdapter doesn’t yet. Methods that propagate a failure throw a bare Error, the open task 7.6 exception; getSession() is the one exception to the exception — it catches the failure and returns null instead of throwing. See Ports & Adapters.

`packages/users-domain/`

A validation package, not a domain. It holds the Zod DTO schemas for the users HTTP surface and nothing else — no entity, no repository, no use case. Better Auth owns the user model.

Config Layer

`apps/monolith/src/config/env.ts`

Every environment variable, validated with Zod. Read it through loadEnv(), never by casting process.env — a raw cast leaves defaults unapplied and string flags like 'false' truthy.

Module Rules

Layer	Can Depend On	Cannot Depend On
`shared-kernel/`	`zod`, `ulid` only	Any framework or infra
`*-ports/`	`shared-kernel/`	Any library it abstracts
`*-adapter/`	its port + the library	`apps/`
`infrastructure/`	`shared-kernel/`	`apps/`
`apps/monolith/`	All of the above	—

Adding a New Seam

packages/<name>-ports/ports/<name>.port.ts — the interface, with JSDoc.
packages/<name>-adapter/<library>.adapter.ts — the implementation.
Add both to apps/monolith/package.json and run bun install.
Wire one field in DIContainer.
Mount routes under apps/monolith/src/services/<name>/.

backend/bun/AGENTS.md § “How to Add a New Domain” is the step-by-step version.

Getting Started

API

Guides

Modules

Modules

Module Organization

Apps Layer

`apps/monolith/`

Packages Layer

`packages/auth-ports/` and `packages/auth-adapter/`

`packages/infrastructure/`

`packages/shared-kernel/`

`packages/users-domain/`

Config Layer

`apps/monolith/src/config/env.ts`

Module Rules

Adding a New Seam

See Also

​Modules

​Module Organization

​Apps Layer

​apps/monolith/

​Packages Layer

​packages/auth-ports/ and packages/auth-adapter/

​packages/infrastructure/

​packages/shared-kernel/

​packages/users-domain/

​Config Layer

​apps/monolith/src/config/env.ts

​Module Rules

​Adding a New Seam

​See Also

Modules

Module Organization

Apps Layer

`apps/monolith/`

Packages Layer

`packages/auth-ports/` and `packages/auth-adapter/`

`packages/infrastructure/`

`packages/shared-kernel/`

`packages/users-domain/`

Config Layer

`apps/monolith/src/config/env.ts`

Module Rules

Adding a New Seam

See Also