Kernlift

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

The top level

my-saas/
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 reads

A 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/

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 toChange
Rename the productsrc/config/site.ts and the artwork in public/; see Rebrand the project
Replace the home pagesrc/components/marketing/example-landing.tsx; see Replace the landing and pricing pages
Change colours or build a screensrc/styles/app.css and src/components/motion; see Use the design system
Change or add copyBoth src/i18n/locales/en/messages.ts and src/i18n/locales/zh/messages.ts; see Add and change copy
Add an admin or workspace pageA 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 providerNothing in code: use /admin/config/*, see Manage configuration
Add a database tableBoth schema files, then a migration for each dialect
Add recurring background workA job in src/server/jobs/scheduled.ts; see Background jobs
Add a feature checkA validator in scripts/validate/, wired into pnpm validate:all
Add a moduleFollow 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:

  1. pnpm typecheck. It needs worker-configuration.d.ts, which pnpm cf-typegen generates, and an up-to-date src/routeTree.gen.ts, which pnpm dev or pnpm build rewrites when routes change.
  2. pnpm check. It reports some pre-existing stylesheet issues. Do not run biome check --write --unsafe across the repository to silence them.
  3. pnpm validate:all.

Next steps