Documentation

Practical guides, quick references, and implementation standards for applying Harmonic Design in real projects.

Getting Started

New to Harmonic Design? Start here:

Understand the framework — what HD is, why it exists, and who it helps
Explore the four pillars — VBD, EBD, BDT, and Project Design
Apply to a real project — follow the practical checklist below

Applying HD to a Project

Phase 1: Volatility Analysis (VBD)

Before writing any structure, answer:

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)

Then draw the boundary map: Managers for stable orchestration, Engines for volatile business logic, Resource Accessors for all I/O, Utilities for cross-cutting concerns.

Phase 2: Experience Decomposition (EBD)

Identify core user journeys and decompose each into:

Experience — the complete journey (e.g., “Onboard a new user”)
Flows — the goal-directed sequences within it (e.g., “Collect user info”, “Select preferences”)
Interactions — the atomic inputs (e.g., text fields, dropdowns, toggles)

Phase 3: Test Strategy (BDT)

Map the test spiral to your components:

Unit tests — Engines and Flows with dependencies mocked at the boundary
Integration tests — Manager → Engine seams, Engine → Accessor seams
E2E tests — Complete user journeys, full stack

Phase 4: Project Plan (PD)

Derive the project plan from the architecture:

Each component → work package
Each dependency → precedence relationship
Critical path → project duration
Float distribution → risk profile

Quick Reference

Communication Rules

The universal rule: state flows downward, results propagate upward, horizontal coordination is prohibited.

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.py

Every 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.

Full documentation including stack-specific implementation guides (Python, Java, TypeScript, .NET, Go), project structure templates, and worked examples is in development.