Architecture / Project note
A quieter architecture for a personal website
Static writing, an independent data API, and a deliberate boundary between the two. A look inside this small corner of the web.
A personal website has two different jobs: give readers a dependable place to read, and give its owner a useful place to keep working. Those jobs do not need the same infrastructure.
This project uses a simple boundary. Article bodies and complete fallback pages are built from Git. The publishing desk updates public details and writing listings through a separate API. Reading an article never waits for that API.
Publishing as a build
Articles are Markdown or MDX files. A single content collection supplies the homepage selection, the archive, article pages, and the RSS feed. A draft is not included in any public output; a future-dated post becomes eligible at the next build after its publication time.
The useful property is consistency: a title in the archive points to an article that was built from the same source. The build supplies a dependable baseline. A public API record can then revise its listing without changing the article body or triggering another deployment.
Git + MDX
├─ Home & writing archive
├─ Article pages
└─ RSS feed
Authenticated client → Worker API → KV documents
Keeping the data boundary clear
The API is a separate Cloudflare Worker with authenticated document reads and
writes. Its storage is a collection of JSON documents in Workers KV, with keys
following the shape docs/{collection}/{id}.
Private collections hold personal notes and small records. The public-site collection holds publishable profile, project, and article-list details. The website validates those responses and updates its editorial layout after load; if the API is unavailable, the Git baseline remains readable.
Internal article links must refer to an existing built page. External writing links can be published directly. A listing update does not rewrite the RSS feed or build-time metadata, and an API draft flag does not withdraw a built article. Those changes still belong in Git. KV propagation can also delay visibility at other locations, so publishing means no rebuild, not a promise of instantaneous global consistency.
Small interactions, useful outcomes
The writing archive filters the already-rendered article list in the browser. Its search includes titles, summaries, topics, and tags. Search and topic filters are reflected in the URL, so a particular view can be bookmarked or shared. Without JavaScript, the complete archive remains readable.
Article pages expose a table of contents, estimated reading time, an update date, and a path to another note. These are small tools for finding and reading the work; they do not change the publishing model.
Leaving room to grow
The next useful additions are more substantial writing and concrete project accounts. A career case study should explain the problem, the author’s role, the options considered, and the result before it earns a place on the homepage.
More infrastructure can wait for a clear need. For now, the important outcome is that the website remains easy to read, revise, and understand.