Skip to content

Developer Architecture

Vivek Sarin edited this page Nov 18, 2026 · 3 revisions

Architecture

This page describes how FlowMotion turns a diagram definition into an animation. Read it before you change any module.

The pipeline

Every input goes through the same stages. The entry point is buildModel in src/model.ts.

source text
  -> parse and validate      (core/parse.ts, text/, story/, drawio/)
  -> shared diagram model    (core/types.ts)
  -> events                  (core/auto.ts: deriveEvents, when no events are given)
  -> timeline                (core/timeline.ts, story/timeline.ts)
  -> layout                  (layout/elk.ts, layout/gantt.ts, layout/flex.ts, layout/fixed.ts)
  -> Model                   (render/model.ts)
  -> SVG and playback        (render/svg.ts, runtime/player.ts)

Model is the output of buildModel. It holds id, animation, layout, timeline, and an optional view. The type is JSON-serializable, and it has no dependency on Obsidian or ELK. Keep it that way: the same model must render in the plugin, in the browser runtime, and in the export script.

Module map

Folder Responsibility
src/core/ The shared diagram types, validation of YAML, default events, timelines, display options (view.ts), src: embed parsing (embed.ts), the starter template
src/text/ The text format (Mermaid and PlantUML style). parse.ts handles headers and directives. kinds.ts handles each diagram kind
src/story/ Storyboards: detection, parsing, and the timeline for beats
src/drawio/ Reading draw.io files, importing their shapes, and sanitising their SVG
src/schema/ The schema for each input format, validation, editor completion, and the fence finder for notes
src/layout/ Graph layout (ELK), time-axis layout for Gantt, flexbox layout for storyboards, and fixed layout for draw.io
src/render/ SVG output, the frame at a given time, row stacking, and the colour theme
src/runtime/ The Player (deterministic playback), the mount function with its controls, and the browser entry point
src/export/ Standalone SVG and HTML output
src/monaco/ FlowMotion language providers, snippets, and theme integration for the optional Monaco runtime
src/obsidian/ The Obsidian plugin: commands, views, dialogs, note language support, and the draw.io helper server

Design rules

  • Untrusted input. Diagram text is untrusted. Validate every field before use. Colour values are validated so they can go into SVG attributes safely.
  • Deterministic playback. Every visual is a pure function of one simulated clock t. A paused, seeked, or exported frame therefore matches the animation at the same time.
  • Limits. The limits are defined once, in LIMITS in src/core/types.ts. See Known limitations.
  • One model for every input. Text, YAML, storyboard, and draw.io inputs all produce the same Model. A new input format should add a parser, not a new renderer.

Where to read next

Clone this wiki locally