Skip to content

Search articles, repositories, topics and pages.

Architecture

Static-First Publishing for a Technical Blog

How this journal separates dynamic authoring from static delivery, with immutable revisions, versioned releases and a CDN in front.

TIAN NEWS AI

Published Updated 2 min read

An editor saving revisions in PostgreSQL, a publisher building a versioned release and a CDN serving it to readers

The constraint

A technical blog is read far more often than it is written. A popular article can get thousands of readers in an hour, while the author edits a few times a week. The architecture should make reading cheap and boring, and keep the moving parts on the writing side.

Dynamic authoring, static delivery

The system has two halves.

  • Authoring is dynamic: an authenticated editor, a database of revisions, previews and a publish button.
  • Delivery is static: pre-rendered HTML and assets on a CDN, with no database query per page view.

Publishing is the bridge between them. It compiles the chosen revisions into a release and switches the public pointer to it.

Immutable revisions and releases

Every save creates or updates a draft; every checkpoint becomes an immutable revision. A release is a complete, versioned snapshot: article HTML, the search index, the RSS feed and the sitemap, all built from the same revisions.

release.ts, ts
type Release = {
  id: string;
  status: "building" | "ready" | "active" | "failed" | "retired";
  articleRevisionIds: string[];
  manifestKey: string;
};

export const canActivate = (release: Release) =>
  release.status === "ready" && release.manifestKey.startsWith(`releases/${release.id}/`);

Because a release never changes after it is built, an infrastructure operator can recover service by activating a retained release pointer. The editorial rollback exposed by this project is deliberately stricter: it copies the selected historical content into a new immutable revision, runs the normal validation and publish pipeline, and records who performed the rollback.

Fail closed

If compilation or validation fails, the release is marked failed and the previous release stays live. Readers never see a half-published site.

CDNs are not atomic

Switching the pointer does not update every edge location at the same instant. For a short window, some readers get the old release and some the new one. That is fine as long as each release only references its own versioned files, so no page can mix old HTML with new assets.

Trade-offs

  • Publishing takes seconds instead of being instant, because it builds and validates a release.
  • The system has more concepts than a single database-backed app: revisions, jobs, releases and pointers.
  • In exchange, reads scale with the CDN, and a broken publish cannot take the site down.

Key takeaway

Keep the database on the writing path and the CDN on the reading path, and connect them with immutable, versioned releases.