Documentation
Practical guides, quick references, and implementation standards for applying Harmonic Design in real projects.
Getting Started
What Harmonic Design is, why it exists, and who it helps. Start with the conceptual foundation before reaching for the tools.
VBD, EBD, BDT, and Project Design — each a complete methodology, each structurally isomorphic with the others.
Follow the four-phase checklist below. Begin with volatility analysis, then decompose experience, map your tests, and derive your plan.
Applying HD to a Project
Before writing any structure, identify where change is concentrated.
- What changes most often? (business rules, UI interactions, schema)
- What almost never changes? (orchestration sequence, core algorithms)
- What crosses a system boundary? (filesystem, network, database, subprocess)
Draw the boundary map: Managers orchestrate, Engines execute, Resource Accessors isolate I/O, Utilities handle cross-cutting concerns.
Identify core user journeys and decompose each into three structural levels.
- Experience — the complete journey (e.g., “Onboard a new user”)
- Flows — goal-directed sequences within it (e.g., “Collect user info”)
- Interactions — the atomic inputs (e.g., text fields, dropdowns, toggles)
Map the test spiral to your component boundaries.
- Unit tests — Engines and Flows; mock at the boundary
- Integration tests — Manager → Engine seams, Engine → Accessor seams
- E2E tests — Complete user journeys, full stack
Derive the project plan directly from the architecture.
- Each component → work package
- Each dependency → precedence relationship
- Critical path → project duration
- Float distribution → risk profile
Quick Reference
Communication Rules
| Call Pattern | Allowed? | Notes |
|---|---|---|
| Manager → Engine | ✓ | Synchronous invocation |
| Manager → Accessor | ✓ | For reads or state persistence |
| Manager → Manager | ✓ (async only) | Fire-and-forget via event bus |
| Engine → Accessor | ✓ | For reference data or persistence |
| Engine → Engine | ✗ | Manager composes instead |
| Accessor → Accessor | ✗ | Manager fetches from both |
| Engine → Manager | ✗ | Upward call forbidden |
| Accessor → Engine | ✗ | Upward call forbidden |
Component Directory Structure
managers/
├── order_manager/
│ ├── i_order_manager.py # Interface (contract)
│ ├── order_manager.py # Implementation
│ └── _helpers.py # Private helpers
engines/
├── pricing_engine/
│ ├── i_pricing_engine.py
│ └── pricing_engine.py
accessors/
├── inventory_accessor/
│ ├── i_inventory_accessor.py
│ └── inventory_accessor.py
utilities/
└── logging/
└── logger.pyEvery component gets its own subdirectory. Interface and implementation can live together — start simple and separate as deployment needs evolve. Components can have private helpers without polluting the tier namespace.