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 consoleEach 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.
| Layer | Lives in | Responsibility |
|---|---|---|
| Routes | src/routes/ | Pages, layouts and API handlers; identity is checked at the boundary |
| Server functions | src/server/functions/ | Calls from loaders and components, each resolving the caller first |
| Services | src/server/services/ | Orchestration, rate limits and side effects across capabilities |
| Repositories | src/server/db/repositories/ | Every read and write, behind dialect-neutral contracts |
| Schema | src/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
| Convention | What it means |
|---|---|
| Spec-driven changes | Every 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 database | Provider credentials and business settings live in /admin/config/*; environment variables cover startup and infrastructure only. See Configuration model |
| No mock providers | Integrations call real test or sandbox environments. Missing credentials surface as a not-configured state, never as a fake success |
| One identity boundary | Only src/server/auth/ reads a session. See Authentication and authorization model |
| A validator per capability | scripts/validate/*.ts asserts behaviour and wiring. See Validators and the release gate |
| One design system everywhere | Admin, 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 optional | No web request path requires the agent service or imports the agent runtime. pnpm validate:optional-agent enforces it |
| Agent skills ship with the code | skills/<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.