The Architecture Beneath the User Experience: Design Lessons from the Grav Helios Course Hub

Building the Grav Helios Course Hub as a plugin that leaves the upstream Grav theme completely untouched – rather than as a custom theme – surfaced nine design principles (see Systems-Oriented Design in Practice for the story behind that decision). Each is worth exploring from two angles – developer and UX – because the same insight often looks different depending on where you're standing.

Nine principles, two angles each

Here they are at a glance, then in full:

• The people who know how a system wants to be extended are often just a conversation away – especially in open source.
• The real question isn't “can I build this?” but “what does it cost to own this instead of the platform?”
• A feature designed for one domain can map directly onto another, if you look at structure rather than labels.
• A constraint you can't work around is often pointing at the right place to work from.
• A concept built in from the start becomes the centre everything else orients around; added later, it's always negotiating with what's already there.
• Every configuration option is a decision the system has transferred to the user.
• What a system offers should depend on where the user is, not just what they ask for.
• Persistent maintenance friction is diagnostic – it points at a structural problem, not just an implementation one.
• Content and the tools that hold it have different lifespans; treating them the same is a mistake that compounds over time.

1. In open source, the people who know exactly how the system wants to be extended are often just a conversation away. Platform creators design extension points intentionally, and in open source that knowledge is often freely shared. What looks like a workaround from the outside is frequently the intended pattern – in this project, a single Discord conversation with the creator of Grav CMS pointed directly to the architecture that made everything else possible.

• Developer: The intended extension point is usually simpler and more stable than anything you'd build around it.
• UX: Patterns the platform already uses are patterns users already understand – find them before inventing new ones.

2. The question is never just “can I build this?” – it's “what does it cost to own this instead of the platform?” A plugin works with the platform at defined seams; a custom theme replaces what the platform already provides, and every decision to build custom is a decision to own the maintenance that comes with it. Designing for the moment a dependency isn't there matters too – if the premium Helios theme isn't installed, the plugin falls back to a working site and guides the user toward the license manager instead of breaking.

• Developer: Every line of custom code is a maintenance liability – the platform's equivalent is someone else's liability.
• UX: A polished platform feature took time to get right. A custom replacement skips that process entirely, and users can feel the difference.

3. A feature designed for one domain can map directly onto another – if you're looking at structure rather than labels. Helios's version switcher, designed for documentation versioning, mapped directly onto course selection. Novel concepts cost: users must learn them, and the system must maintain them – finding an existing structure that already fits your domain eliminates that cost entirely.

• Developer: Repurposing an existing component means inheriting its stability, accessibility, and future updates for free.
• UX: Users already know how to operate the pattern – the learning curve disappears before it starts.

4. A constraint you can't work around often turns out to be pointing at the right place to work from. “Never edit the upstream theme” felt like a constraint at first. It turned out to be a clarifier: shortcodes moved to the plugin, templates were injected rather than overridden, behaviour changed via hooks rather than direct modification.

• Developer: Hard constraints produce architectures that survive updates; convenient shortcuts produce ones that don't.
• UX: Systems built within clear boundaries tend to behave more consistently, and consistent behaviour is the foundation of user trust.

5. When a concept is central from the start, everything else gravitates to it. When it's added later, it orients around everything else. Multi-course support added as a separate skeleton always felt like an extension of something else. Built in from the start, it becomes the natural centre everything else orients around – users experience that architecture even when they can't see it.

• Developer: A feature integrated from the start is coherent with the rest of the system; one added later is always negotiating with it.
• UX: Users can't always articulate why something feels awkward – but they feel it consistently, and it erodes trust.

6. Every configuration option is a decision the system has transferred to the user. Configuration is often framed as flexibility, but it's also a cost. The plugin detects whether one course or multiple are visible and adapts automatically – browser titles, search scope, favicon, and logo link all adjust with no setup required.

• Developer: Context detection requires more thought upfront but eliminates an entire class of user errors.
• UX: Every option added to a settings panel is cognitive load transferred directly to the user.

7. What the system offers should depend on where the user is, not just what they ask for. Search scope shifts automatically based on location: site-wide from the Courses homepage, narrowed to the current course when browsing within it – the same way the original Helios theme narrowed search to the current documentation version.

• Developer: Location-aware behaviour requires knowing the page context at query time – but it eliminates an entire category of “wrong results” frustration users blame on themselves rather than the tool.
• UX: When the system already knows where you are, the results feel less like a search and more like a conversation.

8. Persistent maintenance friction is diagnostic – it points at a structural problem, not just an implementation one. Implementation problems can be fixed by better code. Structural problems can only be fixed by moving a boundary – maintaining two separate skeletons looked like a workload problem, but it was actually a signal that the original design model was wrong.

• Developer: If the same fix keeps reappearing, the problem is the boundary, not the code.
• UX: Friction users keep hitting usually traces back to the same underlying mismatch.

9. Content and the tools that hold it have fundamentally different lifespans – treating them the same is a mistake that compounds over time. Course material often represents significant intellectual work, and content tied to a specific tool risks an expiry date the author didn't agree to. Flat-file Markdown keeps content readable and portable regardless of what happens to Grav, the theme, or the plugin.

• Developer: Flat-file, plain-text formats are the most reliable ones that outlast the tools that create them.
• UX: Users who feel genuine ownership of their content trust the tool more – and depend on it less anxiously.

The further into the project I got, the less I had to decide – Grav's design had already worked that out. A well-architected platform does that: it keeps complexity where it belongs, even when you're no longer thinking about it. The Grav Helios Course Hub is open-source on GitHub, with a live demo – or read Systems-Oriented Design in Practice for how this same thinking shows up across Docsify‑This too.