Core Concepts
The architecture and content model underneath Chinaski: the mental model worth forty minutes before building anything substantial. Everything in this section reflects how the system actually behaves; the Authoring section covers the day-to-day clicking.
In this section
- Architecture: the two-program design: a Perl CMS owning the admin layer, a separate builder process producing the public site, and a web server serving plain files.
- The Build Pipeline: what happens on every build: staging, checks, signing, promotion, and why a build either lands completely or not at all.
- Content Model: pages, posts, blocks, snippets, categories, media, documents: what each type is, and the properties they share (language, trash, revisions, audits).
- Output Structure: what the built site looks like on disk: per-language trees, index files, the redirect files, sitemaps and feeds.
- The Database: one SQLite file as the single source of truth; why an embedded database is the right call here and what it means operationally.
- Instances: running several independent Chinaski sites on one server, and the naming/path conventions that make it safe.
- Background Jobs: the async work queue behind long-running admin tasks.
- Trash: the soft-delete model: what moves to trash, how long it stays, and how to restore it.
- Site Search: how the built-in search index is generated and queried.
The ideas worth internalizing
- The site is build output. The browser-facing site is static files; any edit is invisible until a build runs, and a build either completes (and promotes atomically) or preserves what was already live.
- One database, per-language trees. All state lives in
chinaski.db; the output is a pure function of that database plus your themes and settings, which is what makes backups so simple and rebuilds so safe. - The web server and the CMS only meet deliberately. Static requests never touch the app; only forms, document downloads, and the admin hit it.
- Instance isolation gives one machine many unrelated sites with separate databases, users, and schedules.
Also in Core Concepts
Understand Chinaski's four moving parts, the admin app, the builder, the static output, and the manager, and how they relate to each other.
How a build turns the database into the static site: how it starts, how only one runs at a time, and the swap that only happens on success.
See the content types on a Chinaski site (pages, posts, blocks, snippets, media, navigation) and the foundation they all share.
See the directory tree every build produces: per-language roots, page and post files, and how promotion swaps the live tree.
How Chinaski stores everything in one SQLite file per instance: CHINASKI_DB, WAL mode, the busy timeout, and schema migrations that run at startup.
What a Chinaski instance is: its own app process, database, files, backups, and secret, and what is isolated between instances and what is not.
Run very large content batches through the job queue: submit POST /api/jobs, choose the job type, and poll until the counters settle.
Understand the Trash: which ten content types it covers, how to restore items, and when the 30-day cleanup removes them for good.
Understand the built-in /search/ page: a per-language static JSON index searched in the visitor's browser, what it covers, and how it stays current.