Modules

Module Organization

The Bun Core Platform uses a layered module architecture with three main layers:
  1. Apps — Entry points and orchestration
  2. Packages — Shared code (domain, application, infrastructure)
  3. 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

packages/domain/

Pure TypeScript — zero framework dependencies. Business entities and rules:
packages/domain/
├── entities/              ← Domain objects with identity
│   ├── user.ts
│   ├── session.ts
│   └── message.ts
├── value-objects/         ← Immutable value types
│   ├── email.ts
│   ├── user-id.ts
│   └── session-id.ts
├── events/                ← Domain events
│   ├── user-created.ts
│   └── session-started.ts
└── index.ts
Rules:
  • No imports from hono, mongodb, or any infrastructure
  • Pure TypeScript classes and interfaces only
  • Business logic lives here, not in use cases

packages/application/

Use cases + port interfaces. Depends only on domain/.
packages/application/
├── ports/                 ← Interface definitions
│   ├── user-repository.ts
│   ├── cache-port.ts
│   ├── adapter.ts        ← AI adapter interface
│   └── session-store.ts
├── use-cases/            ← Business workflows
│   ├── create-user.ts
│   └── authenticate.ts
└── index.ts

packages/infrastructure/

Adapters implementing application ports. Depends on application/ + external libraries.
packages/infrastructure/
├── database/             ← MongoDB implementations
│   ├── user-repository.ts
│   └── mongodb-client.ts
├── cache/                ← BunRedis + fallback
│   └── redis-cache.ts
├── i18n/                 ← Translation service
│   └── i18n-service.ts
├── logging/              ← Multi-transport logger
│   └── smart-logger.ts
└── index.ts

Modules Layer

Gateway Module (apps/monolith/src/modules/gateway/)

AI communication layer for OpenClaw integration.
modules/gateway/
├── domain/
│   ├── entities/
│   │   └── session.ts    ← GatewaySession entity
│   ├── ports/
│   │   ├── adapter.ts   ← AIAdapterPort interface
│   │   └── session-store.ts
│   └── index.ts
├── application/
│   ├── use-cases/
│   │   ├── create-session.ts
│   │   ├── get-session.ts
│   │   └── send-prompt.ts
│   └── index.ts
└── infrastructure/
    ├── adapters/
    │   └── openclaw.ts   ← ACP WebSocket client adapter
    ├── session-store/
    │   └── sqlite.ts     ← BunSQLite session store
    └── index.ts

Config Layer

config/MONOLITH_CONFIG.md

Centralized configuration reference for all environment variables.

Module Rules

LayerCan Depend OnCannot Depend On
domain/Nothing (pure)Any framework or infra
application/domain/infrastructure/, apps/
infrastructure/application/
apps/monolith/All layers

Adding a New Module

  1. Create apps/monolith/src/modules/<name>/
  2. Define domain entities in domain/entities/
  3. Define ports in domain/ports/
  4. Implement use cases in application/use-cases/
  5. Implement adapters in infrastructure/
  6. Add routes in apps/monolith/src/api-gateway/routes/
  7. Register in DI container

See Also