Schema Reference

Everything you create in Chinaski (pages, posts, images, forms, users, settings) is stored in a single database file alongside your site. This page explains what the database holds and a few of its behaviors worth knowing as an administrator.

How the database works

The database is a single SQLite file. All data lives in that one file, and backups (manual or scheduled) capture it from there.
Permitted content relationships are enforced by the database itself: deleting a page, post, form, or stack also removes the records that hang off it, such as its form submissions, blocks, and draft edits.
Deleting most content is a soft delete. Deleted pages, posts, blocks, snippets, media, categories, forms, documents, and stacks are flagged, not erased, so recovery and history remain possible. They disappear from lists and the published site immediately. Hard cleanup happens automatically during normal operation.
The database starts with sensible defaults already in place: an English-language site, the built-in default theme (The Letterbox), and a first “admin” account whose password is unusable until you complete first run setup.
Settings are stored as simple name/value pairs, so site options you see in Settings are individually recorded. Each time settings are saved, a snapshot of all values is stored, giving a history of configuration changes.

Content you author

Pages and posts each store their own title, body, and slug. Each language version of a page or post is its own independent record: a slug may exist in one language, several, or all, and nothing forces every language to exist.
Pages and posts carry the fields you see in the editor: SEO titles and descriptions, social share fields, featured image (with focal point), publish/schedule settings, review status, sitemap controls, and an optional password for gated pages.
Pages can hold structured data for product and event listings (name, price, availability, dates, venue); posts share the structured-data type but not those field sets.
Blocks are reusable components, unique per name and language, holding their own text, buttons, colors, and styling. They are attached to pages and posts, with optional per-placement overrides.
Stacks are named, ordered collections of blocks. A stack can be assigned to pages or posts, can stack inside another stack, can have per-language overrides, and can inherit from another stack. The admin area also uses a few internal companion tables to show where a block is used, translate stack content, and report each stack’s build health and performance.
Categories are managed per language; a post saved with a category value is added to the managed category list automatically.
FAQ items and HowTo steps let you attach structured Q&A and step lists to pages or posts for richer search results.
Authors let you maintain bylines: profiles with bio, avatar, and social links, assigned to any number of posts or pages.
Custom fields hold extra key/value data on any page or post, with types for text, numbers, booleans, dates, and JSON.
Drafts auto-save your in-progress edits on the server, so a long editing session survives closing the browser. One draft per user per item.
Revisions are snapshots of every page, post, block, snippet, document, image, stack, and form taken just before each save; this is what powers version history and rollback.
Internal notes can be left on a post without being visible to readers.

Media and documents

Media is the file library: images hold dimensions plus alt text, caption, and credit; uploads record who uploaded them and which folder they live in. Identical files can’t be uploaded twice, and generated image sizes are tracked per file.
Documents manage PDFs with their own URLs, folders, tags, and publish/unpublish scheduling.
Documents support versions with an approval status: drafts move through under review, approved, rejected, or published.
Private documents can be shared through special links with optional expiry and a download limit; all downloads are logged with time, IP, and browser.

Users are admin or editor accounts. An account can be suspended, has a preferred admin language and theme, and can be restricted to certain entities and languages.
Sign-in sessions are tracked, so account pages can show active devices and administrators can sign a user out everywhere.
A record is kept of every sign-in attempt: success, failure, or blocked.
Password reset links are stored without exposing the token itself and stop working once used or expired.
Three small rate-limiting records track repeated failed sign-in attempts, registration attempts, and forgot-password requests per IP address; this is what powers the lockout waits described on the Passwords page.
API keys (stored hashed, never in plain text) authenticate the public REST API, each with its own permissions and optional expiry.
Audit and event logs record every content change (who did what to which item) and system events at info/warn/error levels, so there’s a durable trail of what happened and when.

Forms and submissions

Forms define your contact forms: fields, success page behavior, notification emails, spam protection, and optional webhooks.
Form fields control each input: type, required flag, placeholder, options, conditional display, and validation limits.
Submissions store the entered data, the visitor’s IP (unless you disabled that), a receipt token shown to the submitter, and, where it was provided by the visitor and consented, marketing attribution such as landing-page referrer, UTM parameters, and common ad click IDs. Marking a submission as read is stamped on the record.
Submission answers are also normalized into one row per field, so form results can be filtered and sorted by any single field.

Site configuration and structure

Navigation is a per-language list of header links, supporting external links and nested submenus.
Redirects are created automatically when you rename a published page or post slug, keeping old URLs working; each record counts the hits it has received.
Themes are registered with the site; switching themes remembers which one was active.
Design tokens hold the color/style values that are turned into CSS custom properties at build time.
Design briefs store reference documents used when generating themes.

Builds and background work

Build log records each static-site build: when, outcome, files written, captured output, validation results, and timings.
Build progress is one live-status row updated while a build is running; this feeds the build progress indicator.
Background jobs track longer operations (like imports) with progress counters and results.

Webhooks

Post webhooks are outbound endpoints you define that are notified when a post is published, updated, or deleted.
Delivery log records every webhook attempt: payload, target, response, and retry state.
Circuit breakers stop deliveries to endpoints that fail repeatedly, pausing them for a while instead of hammering a broken destination.

Monitoring

404 log aggregates missing-page reports from the static host or log processor, counting how often each path was requested and when it was last seen.
Backup runs record each backup attempt: whether it was manual, scheduled, made from an API, or pushed; the resulting file and size; and whether the automatic restore-verification check passed.