3 min read · 683 words
Software teams rarely suffer from a lack of frameworks. They suffer from frameworks that do not speak to each other.
A team might apply Domain-Driven Design to their backend, atomic design to their component library, coverage targets to their test strategy, and agile ceremonies to their project management. Each framework is locally sensible. Together, they produce a system where the backend’s bounded contexts do not correspond to the frontend’s component hierarchy, the test strategy was written by convention rather than derived from the architecture, and the project plan was estimated from user stories rather than from the system’s structural dependencies.
When something changes, the engineer must simultaneously reason in four different structural languages. The seams between frameworks become the places where coupling hides and where plans fail.
One Principle Across Every Layer
Harmonic Design is a unified software engineering framework built on a single organizing principle:
Software should be organized by how it changes, not by what it currently does.
This isn’t a new idea in isolation — it’s the underlying insight of four independently developed frameworks that we’ve been building and refining over the past several years. What’s new is the recognition that they all ask the same fundamental question, and that applying that question coherently across every layer of a system produces structural properties that none of the frameworks achieves alone.
The Four Pillars
- Volatility-Based Decomposition (VBD) — Backend system architecture organized around axes of anticipated change. Components are classified as Managers (orchestration), Engines (business logic), Resource Accessors (external boundaries), or Utilities (cross-cutting concerns). Each role isolates a distinct axis of volatility.
- Experience-Based Decomposition (EBD) — Interface architecture built on the same principle. Experiences, Flows, Interactions, and Utilities — the same four volatility axes, applied to the interface layer — because interface change follows the same four axes, just with different drivers.
- Boundary-Driven Testing (BDT) — Test strategy derived from the architecture, not written by convention. The test profile for each component role is determined by its structural position: what it orchestrates, what it executes, and where its boundaries lie. Testing difficulty is diagnostic — if a component is hard to test, its boundaries are in the wrong place.
- Project Design (PD) — Project planning derived from the same structural map. Work packages correspond to components. Dependencies in the project network mirror dependencies in the architecture. Estimation difficulty signals the same class of problem as testing difficulty.
The Structural Isomorphism
The central claim of Harmonic Design is precise: the four pillars are structurally isomorphic. The same four roles appear at every layer, carrying the same responsibilities, the same communication rules, and the same test and planning characteristics — because they isolate the same axes of anticipated change.
| VBD Role | EBD Tier | BDT Scope | PD Work Package |
|---|---|---|---|
| Manager | Experience | Integration test (real orchestrator, mocked deps) | Integration milestone |
| Engine | Flow | Unit test (pure logic) | Core work package |
| Resource Accessor | Interaction | Unit (translation only) | Boundary work package |
| Utility | Utility | Exercised via consumers | Shared infrastructure |
The Whitepapers
Each pillar has a formal whitepaper — written for practitioners who want to understand not just what HD prescribes, but why each decision was made. They are available now on the whitepapers page.
Core Framework
The Harmonic Design overview is the best starting point — it describes the structural isomorphism that connects all four pillars. From there: VBD for backend architecture, EBD for frontend architecture, BDT for testing strategy, and Project Design for planning. Each builds on the previous; together they form a complete engineering system.
AI
The Compiled Context Runtime paper applies the same structural principles to AI agent systems — covering stateless orchestration, process definitions, compiled context injection, and the memory architecture that gives LLM-based systems durable state across sessions.
What’s Coming
Over the next several months we’re publishing deep dives, tutorials, and implementation guides across all four pillars and the stacks they apply to — starting with VBD and moving through EBD, BDT, and Project Design before broadening into case studies, language-specific guides, and the organisational patterns that determine whether good architecture takes root or dies in a pull request.
If you want to follow along, subscribe below. Posts go out twice a week, and every post is grounded in the whitepapers rather than opinion.