返回文章

Small systems, clear boundaries

A few notes on separating content from behavior, keeping a single source of truth, and making software easier to reason about.

Demo article. The examples are illustrative and do not describe a specific private project.

A small system is a good place to practice careful design. There are fewer moving parts, so the relationship between a decision and its consequences is easier to see.

Give each piece of data an owner

Consider a personal blog. Markdown files describe what the author wants to publish. A database serves that content to readers. Page views are produced by visits to the live website.

These three things meet in the same interface, but they do not share the same owner. A content deployment should not decide how many people have opened an article.

type ArticleIdentity = {
  id: string
  slug: string
}

type ReadingStatistics = {
  postId: string
  total: number
}

The stable identifier connects the two records. It lets a title change without erasing the history of the article.

Make the important path visible

A publication pipeline has a useful order: validate the source, build the application, upload the media, deploy the application, and then publish the content.

Each step should report its own outcome. Uploading a file is not the same as finishing a database import. Deploying code is not the same as checking the page a reader will see.

Test the promise

The most useful test often starts with a sentence:

  • Editing an article preserves its reading count.
  • A draft cannot be opened through a direct URL.
  • Switching the interface language leaves the article untouched.

Those sentences can survive a redesign or a different database implementation. They express the promise made to a reader or an author.

Leave room to think

Simple software still needs deliberate choices. A clear boundary is valuable because it reduces the number of things that must be considered at once.

Start with a real need. Make one path work all the way through. Then look at the result, with the same curiosity that made you begin.