Published on January 15, 2025 | Categories: architecture, web-development, technical

Modular Blog Architecture

This blog runs on a modular system where each page is completely self-contained. I built it this way because I wanted the freedom to experiment with different designs and functionality without worrying about breaking other pages.

Why Modular?

After working with AI for a few years, I've noticed that things designed to help human developers often slow down AI. Reusable components and frameworks create complex coupling. Ask an AI to design a blog and it'll probably direct you towards some bloated CMS like WordPress. Using AI to write code like a human is inefficient - it doesn't know what design patterns actually suit it best since it's trained on human-built data.

This system runs on an e2-micro instance on GCP. I have Claude Code running in a tmux session that I can easily jump in and out of. It loads up the small amount of information it needs from a system prompt and can essentially draw a new page with full dynamic functionality in less than a minute.

Page Architecture

Development

HTML Blueprint
config.json + content.md
API Blueprint
api.py with Flask routes
Data Namespace
data/page-name/

Runtime

Static HTML
Compiled page output
API Endpoints
/api/page-name/*
JSON Storage
Thread-safe file ops

Directory Structure

Each page follows a consistent, modular structure:

pages/first-post/ ├── config.json # Page metadata & settings ├── content.md # HTML content + CSS styling ├── api.py # Custom Flask API endpoints └── assets/ # Page-specific resources ├── images/ ├── documents/ └── data/

Key Features

Complete Style Independence

  • Each page has its own CSS
  • No shared stylesheets
  • Zero style conflicts
  • Full design freedom

Custom API Endpoints

  • Page-specific Flask routes
  • Automatic blueprint registration
  • RESTful endpoint patterns
  • Database integration

Asset Management

  • Per-page asset directories
  • Automatic compilation
  • Organized file structure
  • CDN-ready organization

Scoped Data Storage

  • NoSQL file-based database
  • Page-isolated collections
  • Thread-safe operations
  • Firestore-like API

API Integration

Each page can have its own API endpoints. The system automatically registers Flask blueprints, so you get dynamic functionality without any setup.

For example, I recently used this to add a pool ELO system I had running on the server with friends. Claude Code made a complete UI with animations in about 10 minutes. If I have an idea for a post, it can easily clip on interactive elements and give it some life pretty quickly.

Health Check:

API Status: Test the health endpoint

Database System

The database is just JSON files organized by page. Each page gets its own data namespace, so there's no chance of conflicts. It's thread-safe and simple:

data/ ├── pool-leaderboard/ │ ├── players.json │ └── game_history.json └── shared/ └── config.json

Pages can store data with simple calls like db.get_page_data('pool-leaderboard', 'players', {}) or db.append_to_page_collection('pool-leaderboard', 'game_history', new_game). No schemas, no migrations, just JSON.

Simple Benefits

The modular approach has some nice benefits:

Technical Stack

Simple Python setup:

View Source Code on GitHub

It's a choice that gives me freedom. Each page can have completely different styling and functionality without affecting others. The whole thing is pretty straightforward - just a Python compiler that generates static HTML and a Flask server for APIs when needed.