waveform-analysis/docs/architecture.md

Architecture

Waveform Analysis uses a functional architecture around Vue Composition API. Vue composables own reactive orchestration and DOM resources, while pure functions own stateless calculations and state transitions.

Boundaries

• useWaveformChartController is the facade for the chart. It composes composables and exposes the existing reactive controller surface; it owns no independent copy of component props.
• useWaveformViewport keeps refs, computed values, pointer events, DOM capture, D3 coordinates, and emitted events. transitionViewportInteraction and reduceViewportInteraction are pure reducer functions for the legal begin, move, finish, cancel, and reset transitions. The composable's selection shallow ref is the only interaction state source; SVG overlays and pointer capture remain DOM resources local to the composable.
• RenderablePointSelectionStrategy is a function type defining the replaceable rendering algorithm boundary. completePointSelectionStrategy preserves the complete visible source range and peakPreservingPointSelectionStrategy preserves first/minimum/maximum/last points per bucket. resolveRenderablePointSelectionStrategy selects the function from rendering options. The existing selectRenderablePoints function remains the compatibility facade used by rendering.
• normalizeWaveformData and normalizeWaveformSeries are functional adapters from public data shapes to the internal series model. buildTrackLayouts remains a functional builder because layout construction is a stateless calculation, not a long-lived object.

Vue Integration

The viewport selection is stored in a shallow ref and updated only with reducer transitions. SVG overlay elements remain in the composable as DOM resources. Presentation mode, annotation editing, scales, domains, ticks, formatting, and other stateless calculations stay in their existing computed/composable or function boundaries.

Constraints

Do not create classes solely to wrap Composition API refs, props, lifecycle hooks, D3 selections, or pure mathematical helpers. Do not add strategy factories, inheritance trees, global event buses, service locators, or duplicate prop state. Keep pure algorithms and reducer transitions as side-effect-free functions with isolated tests.