Kernlift

Architecture

How the code is layered, why business code never sees a SQL dialect, and the conventions that keep the template forkable.

Kernlift is a template other people fork, so its structure is designed to stay predictable as features are added. Server code is layered, runtime capabilities are detected when the app runs, and a few conventions apply everywhere. For a map of the directories, see Project structure.

The layers

routes/          route components and API handlers
  └── functions/ server functions callable from routes
        └── services/      orchestration across capabilities
              └── repositories/  all database access
                    └── schema/  per-dialect table definitions
platform/        runtime capabilities: cache, storage drivers, edge bindings
jobs/            scheduled work, started by the platform once a minute
agent-host/      the web side of the optional agent service
plugins/         what each installed plugin adds to the console

Each layer may call the one below it. Routes stay thin, services coordinate work that spans capabilities (a settled payment grants credits and issues licences, for example), and repositories are the only code that reads or writes the database.

LayerLives inResponsibility
Routessrc/routes/Pages, layouts and API handlers; identity is checked at the boundary
Server functionssrc/server/functions/Calls from loaders and components, each resolving the caller first
Servicessrc/server/services/Orchestration, rate limits and side effects across capabilities
Repositoriessrc/server/db/repositories/Every read and write, behind dialect-neutral contracts
Schemasrc/server/db/schema/sqlite.ts and postgres.ts, declaring the same tables

Why business code never sees a dialect

Business code calls repositories/ and never uses a SQL dialect directly, so the same code runs on SQLite, Cloudflare D1, Turso and Postgres. The two schema files declare the same tables, and withRepositoryDialect passes a repository the schema for the current connection.

Dialect differences stay inside the schema, migration and adapter layers. Migrations are hand-maintained under drizzle/migrations/<dialect>, so a schema change needs a matching migration in each. How connections and adapters are chosen is covered in Runtimes and database adapters.

Runtime capabilities are facts, not preferences

src/server/platform/ exposes capabilities the runtime either has or does not: a KV namespace for cache, a bucket binding for storage, an inference binding for edge AI. Each is detected at runtime. A capability that is absent is reported as unavailable with the reason, and cannot be selected in admin.

Where a native binding exists, a portable path exists alongside it. Storage has both an S3-compatible driver and a bucket-binding driver behind one interface, so the template stays deployable off Cloudflare.

Caching

Each cache domain keeps its own keys and invalidation timing. Every domain reads its policy (enable, TTL and backend) from admin config, so a domain can be turned off during triage without a deploy. The policy is edited at /admin/config/cache.

Plugins fill the console

The admin sidebar, the workspace sidebar, the dashboard cards and the billing actions are slots, declared in src/plugins/slots.ts, that installed plugins fill. src/plugins/installed.ts is the explicit list of plugins in a build: the builtin foundation plugin, which carries every console entry the foundation ships, and one plugin per installed module. Server-only contributions are listed separately in src/plugins/installed.server.ts.

A plugin can be switched off at /admin/plugins. Its entries then disappear and the /admin and /app layouts return not found for its pages. Its data stays. See Plugins.

Background work runs in the web app

Recurring work belongs to runScheduledJobs() in src/server/jobs/scheduled.ts: credit expiry, billing fulfilment retries and unfinished AI tasks. One round runs a minute, started by whatever the platform offers: the in-process loop on a Node server, the Worker's Cron Trigger on Cloudflare, or an external cron calling pnpm jobs:run. A lock row in the config table keeps it to one round even with several replicas, and each round records a heartbeat that /setup reads. See Background jobs.

The agent is a separate, optional service

The agent workbench runs in apps/agent-service, a second process built from the agent-* workspace packages under packages/. The web app never loads the agent runtime and no web request depends on that service. src/server/agent-host/ is the web side of the boundary: getAgentAvailability() in availability.ts returns whether this deployment has an agent, and navigation, pages and /api/agent/* all use that result. A deployment without the service is a complete web app whose AI goes through the plain channel calls. See Agent runtime.

One build per deployment target

deploy.config.json records the platform (cloudflare, fly, railway or docker), the database and whether the agent is deployed. It is bundled at build time and also picks the build: the Worker build with src/server-entry.ts, or the Node build with src/server-entry.node.ts. kernlift deploy-target rewrites it. See Runtimes and database adapters.

Locales

Routes are locale-aware under src/routes/{-$locale}/: the same page serves English at /… and Chinese at /zh/…. Copy lives in src/i18n/locales/{en,zh}/messages.ts with identical keys, and components read their copy from those dictionaries. Copy that belongs to one console area can sit in a file of its own under src/i18n/, with the same en and zh keys. See Add and change copy.

Conventions that apply everywhere

ConventionWhat it means
Spec-driven changesEvery non-trivial change starts as an OpenSpec change in openspec/changes/ with a proposal, design, specs and tasks, and is archived when done
Configuration in the databaseProvider credentials and business settings live in /admin/config/*; environment variables cover startup and infrastructure only. See Configuration model
No mock providersIntegrations call real test or sandbox environments. Missing credentials surface as a not-configured state, never as a fake success
One identity boundaryOnly src/server/auth/ reads a session. See Authentication and authorization model
A validator per capabilityscripts/validate/*.ts asserts behaviour and wiring. See Validators and the release gate
One design system everywhereAdmin, workspace, auth, system and public-site pages are all built from beUI (packages/beui, src/components/motion) with Tailwind utilities on tokens that live on :root. No surface opts in and no page carries a prefix of its own. src/styles/app.css carries historical !important debt that new files must not copy. See Use the design system
The agent is optionalNo web request path requires the agent service or imports the agent runtime. pnpm validate:optional-agent enforces it
Agent skills ship with the codeskills/<name>/SKILL.md holds the skills for working on the project. They name only commands, paths and routes that exist

Modules are slices of one repository

The checkout is a single repository. Each module is described by modules/<key>/module.json, and shared files carry @module:<key> regions. pnpm registry:build slices the checkout into a foundation item plus one item per module, and pnpm validate:registry proves the slices reassemble into the checkout byte for byte and that the foundation compiles without any module. See What the base repository contains.

Files

src/routes
src/server/functions
src/server/services
src/server/db/repositories
src/server/auth
scripts/validate/auth-boundary.ts
src/server/agent-host/availability.ts
scripts/validate/optional-agent.ts
src/plugins/installed.ts
src/plugins/slots.ts
src/plugins/foundation/plugin.ts
src/server/jobs/scheduled.ts
packages/beui
apps/agent-service
deploy.config.json
src/server/platform/deployment.ts

Next steps