Project structure
Find your way around a Kernlift checkout and know where each kind of change belongs.
A Kernlift project is one repository: the application, its migrations, validators, agent skills, the optional agent service and the tooling that packages it into modules. This page shows where each part lives. The reasons behind the layout are in Architecture and layers.
Before you begin
- A project cloned and installed with the Quick start.
The top level
src/ the web application (routes, components, plugins, server code, copy)
packages/ workspace packages: beui (the design system), kernlift-skills, and the agent-* packages
apps/agent-service/ the optional agent service, a separate process (agent-starter module)
drizzle/migrations/ hand-maintained migrations, one directory per dialect: sqlite/ and postgres/
scripts/ db/, jobs/, validate/, registry/, assets/, skills/, plus the Node and Worker smoke tests
modules/ one module.json per module, plus the foundation manifest
skills/ agent skills for working on the project (quick-start, new-page, deploy, ...)
agent-skills/ skills the agent itself runs (agent-starter module)
tools/kernlift/ the kernlift CLI package
openspec/ specs and change proposals (openspec/changes/)
docs/ maintainer notes and design references
public/ icons, share image and placeholder artwork
deploy.config.json the platform, database and agent choice this build is made for
wrangler.jsonc Cloudflare Worker entry and bindings (Cloudflare projects only)
Dockerfile the Node image every other platform runs
.env.example every environment variable the source readsA project carries only its own platform's deployment files: wrangler.jsonc on Cloudflare,
fly.toml on Fly.io, .railway/railway.ts on Railway, compose.yaml for Docker.
kernlift deploy-target <platform> switches between them and rewrites deploy.config.json. The
product documentation you are reading is published from the store project and is not part of your checkout.
Inside src/
routes/{-$locale}/ pages; the optional locale segment serves /zh routes
app.tsx, app/ signed-in workspace (/app/*), guarded once in the layout
admin.tsx, admin/ admin console (/admin/*), guarded once in the layout
routes/api/ API handlers such as /api/billing/*, /api/chat and /api/agent/*
components/ UI grouped by capability
motion/ the beUI components pages import
admin/ admin page patterns (records, metrics, panels, config forms)
marketing/ the public site: shell, page-shell primitives, landing, pricing
layout/ AppShell and the workspace sidebar
plugins/ console plugins: the foundation plugin and one per module, with the
slots they fill (admin.nav, app.nav, dashboard cards, billing actions)
i18n/ locales/{en,zh}/messages.ts plus per-feature copy files
config/site.ts site name, canonical URL, description and social image
styles/app.css the product tokens on :root, shared by every page
server/
auth/ the only code that reads a session: context, guards, API boundary
functions/ server functions called from routes and components
services/ orchestration across capabilities
db/repositories/ all database access
db/schema/ sqlite.ts and postgres.ts, the same tables in two dialects
jobs/ scheduled work: runScheduledJobs() and the in-process loop
agent-host/ the web side of the agent: availability, transport, credits, storage
plugins/ plugin state and the API routes plugins contribute
platform/ runtime capabilities: cache backends, storage drivers, bindings, deployment
server-entry.ts the Worker entry named in wrangler.jsonc
server-entry.node.ts the server entry of the Node build (pnpm build:node)Each server layer calls only the one below it, so business code never touches a SQL dialect. The
web app runs without apps/agent-service. When the service is absent, agent entries report that it
is not deployed.
Where your changes go
| You want to | Change |
|---|---|
| Rename the product | src/config/site.ts and the artwork in public/; see Rebrand the project |
| Replace the home page | src/components/marketing/example-landing.tsx; see Replace the landing and pricing pages |
| Change colours or build a screen | src/styles/app.css and src/components/motion; see Use the design system |
| Change or add copy | Both src/i18n/locales/en/messages.ts and src/i18n/locales/zh/messages.ts; see Add and change copy |
| Add an admin or workspace page | A route under src/routes/{-$locale}/admin/ or app/ and a navigation entry in src/plugins/foundation/plugin.ts; see Add an admin or workspace page |
| Connect a provider | Nothing in code: use /admin/config/*, see Manage configuration |
| Add a database table | Both schema files, then a migration for each dialect |
| Add recurring background work | A job in src/server/jobs/scheduled.ts; see Background jobs |
| Add a feature check | A validator in scripts/validate/, wired into pnpm validate:all |
| Add a module | Follow the new-module skill; see Build a module |
Keep provider settings out of the environment
Environment variables cover only startup and infrastructure. Feature code does not read
process.env; provider credentials belong in the admin console.
Verify
Run the checks you will run before every change is finished, in this order:
pnpm typecheck. It needsworker-configuration.d.ts, whichpnpm cf-typegengenerates, and an up-to-datesrc/routeTree.gen.ts, whichpnpm devorpnpm buildrewrites when routes change.pnpm check. It reports some pre-existing stylesheet issues. Do not runbiome check --write --unsafeacross the repository to silence them.pnpm validate:all.