---
title: "Core Concepts"
url: "https://docs.chinaski.net/en/concepts/"
type: "page"
language: "en"
description: "Learn the architecture and content model behind Chinaski: the two-program design, the build pipeline, and what pages, posts, and blocks are."
updated: "2026-09-29"
generated: "Markdown rendition of the HTML page at url, built by Chinaski"
---

# 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](https://docs.chinaski.net/en/concepts/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](https://docs.chinaski.net/en/concepts/build-pipeline/)**: what happens on every build: staging, checks, signing, promotion, and why a build either lands completely or not at all.
- **[Content Model](https://docs.chinaski.net/en/concepts/content-model/)**: pages, posts, blocks, snippets, categories, media, documents: what each type is, and the properties they share (language, trash, revisions, audits).
- **[Output Structure](https://docs.chinaski.net/en/concepts/output-structure/)**: what the built site looks like on disk: per-language trees, index files, the redirect files, sitemaps and feeds.
- **[The Database](https://docs.chinaski.net/en/concepts/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](https://docs.chinaski.net/en/concepts/instances/)**: running several independent Chinaski sites on one server, and the naming/path conventions that make it safe.
- **[Background Jobs](https://docs.chinaski.net/en/concepts/jobs/)**: the async work queue behind long-running admin tasks.
- **[Trash](https://docs.chinaski.net/en/concepts/trash/)**: the soft-delete model: what moves to trash, how long it stays, and how to restore it.
- **[Site Search](https://docs.chinaski.net/en/concepts/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

[Architecture](https://docs.chinaski.net/en/concepts/architecture/)

Understand Chinaski's four moving parts, the admin app, the builder, the static output, and the manager, and how they relate to each other.

[The Build Pipeline](https://docs.chinaski.net/en/concepts/build-pipeline/)

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.

[Content Model](https://docs.chinaski.net/en/concepts/content-model/)

See the content types on a Chinaski site (pages, posts, blocks, snippets, media, navigation) and the foundation they all share.

[Output Structure](https://docs.chinaski.net/en/concepts/output-structure/)

See the directory tree every build produces: per-language roots, page and post files, and how promotion swaps the live tree.

[The Database](https://docs.chinaski.net/en/concepts/database/)

How Chinaski stores everything in one SQLite file per instance: CHINASKI_DB, WAL mode, the busy timeout, and schema migrations that run at startup.

[Instances](https://docs.chinaski.net/en/concepts/instances/)

What a Chinaski instance is: its own app process, database, files, backups, and secret, and what is isolated between instances and what is not.

[Background Jobs](https://docs.chinaski.net/en/concepts/jobs/)

Run very large content batches through the job queue: submit POST /api/jobs, choose the job type, and poll until the counters settle.

[Trash](https://docs.chinaski.net/en/concepts/trash/)

Understand the Trash: which ten content types it covers, how to restore items, and when the 30-day cleanup removes them for good.

[Site Search](https://docs.chinaski.net/en/concepts/search/)

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.
