Architecture
one Node.js process, two SQLite files.
Kiln is one Node.js process. It serves the builder app, the operator console, the API, the published sites and the form endpoint, and it stores everything in SQLite files and an image folder. Outside services are called only when you have set them up.
01Components and data flow
In words:
- Staff and clients use the builder at
/app, a React app compiled intoweb/dist/. It talks to/api. - The operator uses the console at
/admin(Admin Kit). Kiln's own data screens (Workspaces, Sites, Users, Plans, Credit packs, AI usage) are framed from/console/<page>. - AI calls go from the server to the provider you chose, with your key. The browser never sees the key.
- Images from uploads, Pexels and OpenAI are saved in
data/media/and served at/media/<file>. - Built-in hosting: the server answers requests for
<site>.<sites domain>, verified custom domains and/s/<site>/with the published copy of the site, rendered by the same renderer the editor uses. - Cloudflare: on Deploy, the server renders every file and uploads it to your Cloudflare account. Visitors are then served by Cloudflare, not by your server.
- Forms on every published, deployed or exported site post back to
<public URL>/f/<site id>. - Stripe: clients pay on Stripe Checkout; Stripe calls
/webhooks/stripe, which adds credits, changes plans and records payments. - Resend sends invites, resets, review decisions and form notices when it is configured.
02Request order
src/server/app.ts handles a request in this order: a published site on its own host name; /healthz and /favicon.ico; /api (builder API, with the x-kiln header check on changes); /webhooks/stripe; public routes (/media, /s, /f, /review); /console; the builder app at /app; finally the Admin Kit, which answers /admin and every unknown path.
03Storage
data/kiln.sqlite: users, sessions, workspaces, members, invites, sites (each site is one JSON document, with versions as snapshots), domains, reviews, form submissions, media records, plans, credit packs, the credit ledger, AI usage, payments, processed Stripe events.data/admin.sqlite: the Admin Kit's settings, encrypted secrets, console users, sessions and audit log.data/media/: image files.
Tables are created automatically on start. SQLite runs in WAL mode.
04Where to change things
| Folder or file | What lives there |
|---|---|
src/server/index.ts | Start-up: reads .env, opens the databases, starts the Admin Kit and the HTTP server. |
src/server/config.ts | Environment variables. |
src/server/app.ts | Routing order, the builder app's static files. |
src/server/routes/ | auth.ts accounts and invites, sites.ts builder API, hosting.ts hosting, forms and review links, billing.ts Stripe routes, console.ts console product pages. |
src/server/admin/ | manifest.ts every console setting, page and check; kit.ts checks, key tests, revenue and statistics. |
src/server/ai/ | provider.ts the AI providers; generate.ts prompts, the copy rules and schemas. |
src/server/publish/ | cloudflare.ts the Cloudflare deploy; export.ts the HTML and Astro ZIPs. |
src/server/billing.ts, media.ts, notify.ts | Stripe, the media library, e-mail. |
src/server/db.ts, store.ts | Database schema and data access. |
src/shared/blocks.ts | The 21 section types: fields, variants, defaults. |
src/shared/render.ts, site-css.ts | The HTML renderer and the published sites' stylesheet. |
src/shared/theme.ts, templates.ts | Style presets, fonts, templates. |
src/shared/quality.ts | The checks and the score. |
web/src/ | The builder app: pages/ (sign-in, sites, new site, templates, team, billing), editor/ (editor, canvas, inspector fields, panels, publish dialog), styles.css. |
public/console.* | The console's product pages. |
packages/admin-kit/ | The operator console (server, contract, built UI and its source). |
test/ | Automated tests (npm test). |
After changing code, run npm run build and restart. npm run dev runs the server from source with automatic reloads, and npm run dev:web runs the builder app with hot reloading during development.