Design Principles

Chinaski describes its own rulebook in its source material: some rules are engineering positions, some are promises about behavior, and some are contributor-facing style rules. This page gathers the rules the project holds itself to, useful if you’re evaluating the software, or planning to work on it.

The promises

• Small dependency list. There are nine production dependencies, and that number is a target the project refuses to grow carelessly. Every one of them ships with the operating system, which is what makes fresh installs reproducible and audits tractable.
• No running code for readers. The public site is plain files; the publishing app never answers reader requests. Reader-facing pages carry no runtime JavaScript; this is structural: there is no mechanism through which a tracker or beacon could be added, so it cannot be shipped “accidentally.”
• The site works after install without pods of cloud services. No telemetry, no license server to phone, no fonts or icons pulled from other people’s CDNs. Air-gap operation is a stated rule; even planned commercial licensing was designed to work offline.
• Builds are deliberate. Publishing never happens silently in the background: a build is something you trigger (from the dashboard, a webhook, or the command line), always with logs you can inspect afterwards.
• Trade-offs are stated, not buried. The project says plainly what it will not do: no drag-and-drop editor yet, no plugin ecosystem, a single-tenant database, and self-hosting responsibility stays with you. Nothing on this list is negotiable-by-marketing; if it doesn’t exist, the docs say it doesn’t exist.

The reasoning behind them

• Boring beats clever: the language of the core hasn’t changed its idioms in decades, the database treats your data as a file, and dependencies don’t rename themselves under you. A program written years ago still runs, and an unfamiliar operator can read the code top to bottom at 2 a.m.
• Attack surface is a design decision. Every feature somebody proposes makes a bet: is the capability worth the surface it adds? The project’s position is that most bets lose in production, so the safest default is to say no until proven otherwise; hence no hooks, no plugin registry, no marketplace.
• AI-assisted, human-auditable. The codebase is developed with AI assistance, and the project treats AI fluency, not Perl fluency, as the contributor-entry skill, precisely because boring, stable code stays readable by people and LLMs alike, thirty years of consistent idiom at a time.

The contributor rules

If you’re working on the admin interface, the implementation notes are explicit:

• No inline styles: use the provided utility classes.
• No decorative icons; any icon must be paired with a visible text label.
• The color palette is closed: new colors break the system’s consistency; use the existing CSS custom properties.
• Keep nesting shallow; class naming follows BEM-ish conventions.
• Buttons in headers and card footers go in the prescribed action containers.

For block templates, the block specification is the authoritative reference, written to be followed by a human or an AI working from the spec alone, with every block type consisting of a builder template and an admin form partial as a matched pair. Block types must be registered with the system before use.

Working in the public theme system instead? The Template Reference has its own rules: flat variables, _-prefixed partials, forbidden directives, the password-gate requirement, and they apply to theme authors rather than contributors to the admin UI.

What’s planned (and stated as not shipped)

• A drag-and-drop visual editor: on the roadmap, blocked on page-structure decisions; does not exist today.
• LLM content generation tied to the block library; planned, commercial tier.
• Click tracking with campaign attribution: the planned commercial module.
• Multi-tenancy with Postgres: on the roadmap, not started; the migration path isn’t defined yet.

Commercial Pro modules are designed to be licensed locally (signed license files, no external validation) so the air-gap promise survives monetization, and the core stays MIT-licensed with Pro features living in a separate namespace.

The one-line summary

Every rule above reduces to the same discipline: reduce surface area, prefer nothing that needs a network or a plugin to be safe, keep output dumb, log heavily, document trade-offs honestly, and hold the line when a tempting feature asks you to break the rule.