Architecture
High-Level Design
Key Components
API Gateway (Hono)
Entry point for all client requests. Handles cross-cutting concerns:- Rate Limiting — Sliding window per user/IP
- Idempotency — Safe retries with
Idempotency-Keyheader - i18n — Locale detection + translation
- Logging — Request/response tracking
- Errors —
error.middleware.tsmapsLocalizedErrorandApplicationErrorto their own status codes; everything else becomes a 500
Service Routes
Hono routers underapps/monolith/src/services/. There is no separate use-case layer, and no
single flow all of them follow:
services/users/api.ts’s/registerand/login— the only twoAuthPortroutes: Zod DTO →container.authPort→AuthAdapter; see Ports & Adapters.roles,admin, andorganizations— several handlers callcontainer.roles.customRoles, a direct call to theCustomRolesRepositoryclass (DIContainertypes this field as the concrete repository, notICustomRolesRepository, so it is not a swapped-through port the waycontainer.authPortis). Most other handlers in these and other services build a Drizzle query directly againstDATABASE_URL, with no port in between. Some handlers validate with a Zod schema first (PATCHroutes typically do); severalGEThandlers take no input to validate.- A few routes — including
services/auth/api.ts’s/app-token— call Better Auth’s own API (container.auth.api...) directly, or run SQL with no schema at all.
Ports & Adapters
The port is an interface this codebase owns; the adapter implements it with someone else’s library.AuthPort → AuthAdapter (Better Auth) is the reference arrangement
(ADR-0053), and
Ports & Adapters is the guide.
- PostgreSQL — the only database. Drizzle ORM; Better Auth owns the auth schema
- BunRedis — cache with in-memory fallback, behind
ICache - File System — i18n JSON files
There is no
packages/domain/ or packages/application/, no entity layer, and no use
cases. A port plus an adapter is a complete hexagon here. users-domain once had entities,
a repository and use cases; nothing ever called them and they were deleted (ADR-0053).Design Principles
Data Flow
This is the path for/users/register and /users/login — the only two AuthPort routes. Both
are public: they register only validateBody, not authMiddleware, which starts at protected
routes like /users/me. The custom-role handlers in roles, admin, and organizations call
container.roles.customRoles directly — a concrete CustomRolesRepository, not a port in the
middle — which is a separate flow from the one below. Most other routes skip step 4 entirely and
call Drizzle or Better Auth’s API directly from the route handler.
Key Architectural Decisions
1. Monolith Over Microservices
The Bun Core Platform is a monolith (single deployable unit). This is intentional:- Simplicity — One server to deploy, monitor, debug
- Co-location — No network latency between modules
- Transactions — ACID across modules without distributed coordination
- MVP speed — Faster to build and iterate
2. ACP WebSocket as Client — PLANNED, NOT BUILT
The gateway module would connect to OpenClaw as a client, not a server:- Single WebSocket per agent (multiplexed sessions)
- JSON-RPC 2.0 message framing over WebSocket
- Async iterable for streaming responses
3. BunSQLite for ClawUI Sessions (Zero Infra) — PLANNED, NOT BUILT
Login sessions are not stored this way. Better Auth owns thesession table in PostgreSQL.
The design below is for ClawUI’s own chat sessions, which are unbuilt:
- Zero infrastructure — embedded SQLite file
- Fast for session workloads (key-value + history)
- TTL-based expiration for old sessions
- Falls back to Redis if configured for distributed setups
Gateway Prompt Flow (SSE) — PLANNED, NOT BUILT
Performance Considerations
Cold Start
- Bun: ~10ms cold start
- Hono: < 1ms route matching
- PostgreSQL connection pool: lazy —
drizzle(DATABASE_URL)does not connect until the first query
Request Latency
Security
Middleware Stack
- Rate Limiting — Per user/IP, sliding window
- Idempotency — Prevents duplicate submissions
- Authentication —
authMiddlewareverifies in-process (Better Auth session cookie, or a bearer JWT), not an upstream proxy - i18n — No user input in error messages
- Logging — Correlation IDs for audit trails
WebSocket Security
- Token validation on connect
- Per-session authorization via
_meta.sessionKey - No sensitive data in WebSocket URLs