Content Platform Architecture

Architecture Decisions

This document records the key architectural choices for the content platform. Built with the Pragmatic tech choices and Simplicity lenses.

Why a static site generator?

• No runtime dependencies: static HTML can be served from any web server or CDN
• Version-controlled content: markdown files in git give us full history
• Zero database overhead: no CMS database, no caching layers needed
• Build-time validation: broken links, missing images caught at build time

Why custom over off-the-shelf?

For the initial workflow, a small custom script was chosen over existing tools (Hugo, Jekyll, Astro) because:

1. Zero install: Python 3 stdlib + PyYAML (already available) — no npm install, no framework
2. Minimal abstraction: ~150 lines of build script is fully auditable
3. Complete control: the workflow is exactly what we need, nothing more
4. Easy to replace: the interface (markdown in → HTML out) is the industry standard

When the content pipeline grows beyond this script's capability, migration to Hugo or Astro is a one-afternoon project.

Content pipeline stages

Author writes markdown → git push → build script → static HTML → deploy

Each stage is automated:

1. Authoring: any text editor, markdown files in content/
2. Version control: git add, git commit, git push
3. Build: python3 build.py generates HTML in public/
4. Deploy: copy public/ to web server or configure GitHub Pages / Netlify

Future considerations

• Caching: only rebuild changed files (content hashing)
• Images: automatic resizing and optimization pipeline
• Analytics: embed or post-build injection of tracking
• Search: client-side search index from content