Repository navigation
Developer Architecture
Vivek Sarin edited this page Nov 18, 2026
·
3 revisions
This page describes how FlowMotion turns a diagram definition into an animation. Read it before you change any module.
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.
| 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 |
- 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
LIMITSinsrc/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.
- Input formats for the parsers and their dispatch order.
-
Rendering and playback for the SVG and the
Player. - Obsidian plugin for the plugin code.
© 2026 @vrsarin. FlowMotion documentation.