The right architecture and the right tool don't just solve a problem – they reframe what the problem was.

Mine started with a single Discord conversation and a question: "how do I change one label in this theme?"

I needed to change "Version" to "Course" in the navigation switcher for the brand new Grav premium Helios theme, as I saw its potential as a successor to my original Open Course Hub. Andy Miller, the creator of Grav CMS, kindly pointed me in a direction I hadn't considered: handle everything in a dedicated plugin and leave the theme files completely untouched. "That one plugin is their entire customization. Keeps everything else stock." He also suggested Claude Code as a tool to help bridge the gap between the architecture and actually building it.

The Grav Helios Course Hub is my third generation open course companion. The previous version eventually split into two separate projects, single-course and multi-course, and naturally maintaining both resulted in more effort. That friction turned out to be a signal: multi-course wasn't a variant of the design, it was the default use case that could handle both. And using a premium theme made sense on multiple levels – revenue from Helios licenses directly funds continued development of the open-source Grav CMS itself.

This experience led me to nine design principles, each circling back to the same question: where does this complexity actually belong?

Nine principles emerged from that process. Each is explored from two angles – developer and UX – because the same insight often looks different depending on where you're standing

The Nine Principles at a Glance

1. In open source, the people who know exactly how the system wants to be extended are often just a conversation away.
2. The question is never just "can I build this?" – it's "what does it cost to own this instead of the platform?"
3. A feature designed for one domain can map directly onto another – if you're looking at structure rather than labels.
4. A constraint you can't work around often turns out to be pointing at the right place to work from.
5. When a concept is central from the start, everything else gravitates to it. When it's added later, it orients around everything else.
6. Every configuration option is a decision the system has transferred to the user.
7. What the system offers should depend on where the user is, not just what they ask for.
8. Persistent maintenance friction is diagnostic – it points at a structural problem, not just an implementation one.
9. Content and the tools that hold it have fundamentally different lifespans – treating them the same is a mistake that compounds over time.

The Design Principles

1. In open source, the people who know exactly how the system wants to be extended are often just a conversation away.