Replaced WordPress with a custom CMS

Architecture Decision Record

Status

accepted

Context

WordPress was already installed at public_html/ root on web hosting. When I started building the portfolio routing, WordPress .htaccess was intercepting every request before my PHP files could run. Fixing the conflict meant either working around WordPress or removing it entirely.

Rationale

The .htaccess conflict was the trigger but not the real reason. WordPress has a content model built around posts, pages, and categories. That's not how I think about engineering documentation. I needed entry types — journal, AI collaboration log, architecture decision, learning resource. I needed projects as the primary container with entries scoped underneath. WordPress would have forced me to bend my content model to fit its structure. Building a custom CMS meant the schema matched how I actually think about this work. More build time upfront, full control permanently.

Trade-offs

WordPress would have been faster to launch — themes, plugins, editor out of the box. The custom CMS took several sessions to build and debug, including routing issues on LiteSpeed that WordPress handles automatically. The tradeoff was time now for a content model that actually fits the purpose. For a portfolio that's meant to document engineering thinking, having the right structure matters more than getting live faster.

WordPress was running when I started. The first sign of trouble was a 403 error on the homepage — a routing conflict I kept misdiagnosing.

Once I traced it to the WordPress .htaccess intercepting requests before my PHP router ran, I had a choice: work around WordPress or remove it.

I removed it.

The routing fix was the practical reason. But the more honest reason is that WordPress would have owned the structure. Posts and pages don't map to what I'm building here. A project isn't a post. An AI collaboration log isn't a page. The relationships between them — entries scoped to projects, standalone journal entries, ADRs with structured fields — none of that fits naturally into WordPress without significant plugin work.

Building from scratch meant I could define exactly the content model I needed. The database schema reflects how I think about this work, not how a general-purpose CMS thinks about content.

Longer to build. Worth it.