Architecture

The source of truth is ARCHITECTURE.md in the repository. This page is a summary.

Packages

Path	Package	Status
`packages/core`	`@quickben/core`	Available
`packages/db-memory`	`@quickben/db-memory`	Available
`packages/adapter-tests`	`@quickben/adapter-tests` (private)	Available
`packages/db-drizzle`	`@quickben/db-drizzle`	Available
`packages/next`	`@quickben/next`	Available
`packages/admin`	`@quickben/admin`	Available
`packages/plugin-tenancy`	`@quickben/plugin-tenancy`	Planned
`packages/create-quickben`	`create-quickben`	Planned
`apps/docs`	This site	Available
`apps/playground`	Next.js app using everything (PGlite)	Available

Dependencies point one way. Adapters and other packages depend on @quickben/core as a peer dependency. Core depends only on Zod.

Layers


quickben.config.ts      collections, fields, access, hooks, plugins
        │
        ▼
defineConfig            applies plugins in order, validates slugs and relations
        │
        ▼
local API (qb)          access → hooks → Zod validation → relations → transaction
        │
        ▼
DatabaseAdapter         memory, Drizzle (Postgres, PGlite, SQLite), others later

The route handlers and the admin UI call the local API. They do not talk to the adapter directly.

Next.js integration

File	Package	Export
`app/api/[...quickben]/route.ts`	`@quickben/next`	`createRouteHandlers(config)`
`app/admin/[[...segments]]/page.tsx`	`@quickben/admin`	`createAdminPage(config, { serverFunction })`
`app/admin/layout.tsx`	`@quickben/admin`	`import "@quickben/admin/styles.css"`

Package	Runs on the server	Runs in the browser
`@quickben/next`	Route handlers, `getQuickben`, `getRequestContext`	Nothing
`@quickben/admin`	Shell, dashboard, list and edit views, one server function	Form submit and errors, relation picker, JSON editor, delete dialog, toast

Core responsibilities

Concern	Done by	Detail
Types	core	Inferred from fields. No code generation.
Validation	core	Zod 4 schemas generated from fields, then field `validate`.
Access	core	Rules per operation; filters AND-ed with queries.
Hooks	core	Run inside the write transaction.
Relations	core	Stored as ids; loaded by core with `depth` (0–3).
Cursors	core	Keyset positions turned into `where` filters.
Ids	core	UUIDv7.
Storage and query	adapter	`find`, `findOne`, `count`, `create`, `update`, `delete`, `transaction`.
Unique values	adapter	Throws `ConflictError`.

Tooling

Tool	Version
Node.js	22.18 or later (CI: 22 and 24)
pnpm	12, pinned with Corepack
TypeScript	6.0
ESLint	10, flat config
tsdown	0.23
Vitest	5
Turborepo	2

All packages are ESM only, TypeScript strict, with exports maps.