MindMapper: Architecture of a Local-First Infinite Canvas
A technical deep dive into building an open-source visual thinking engine: HTML5 Canvas rendering, superellipse squircle math, curved synaptic Bezier routing, and zero-telemetry local storage.
When building modern graphical editors and mind-mapping tools, engineers frequently default to DOM-based SVG trees or complex third-party graph frameworks. While convenient, these approaches quickly introduce performance degradation, layout recalculation bottlenecks, and opaque telemetry layers.
MindMapper was engineered from first principles as an open-source, zero-dependency, local-first infinite canvas. By unifying raw HTML5 Canvas 2D immediate-mode rendering, mathematical squircle geometry, and a command-pattern undo/redo engine, it delivers frictionless 60fps visual thinking for engineers, architects, and educators.
Architectural Highlights
- Immediate-Mode Rendering: Canvas 2D context direct draw calls eliminate DOM tree overhead, guaranteeing 60fps pan and zoom across 1,000+ connected nodes.
- Lamé Superellipse Squircles: Mathematical curve formulas yield organic rounded node boundaries with dynamic multi-line text measurement.
- Synaptic Bezier Vectors: Dynamic magnetic anchor solvers ensure connecting curves terminate cleanly at node perimeters with rotational arrowhead geometry.
- Local-First & Sovereign: Complete offline functionality, zero tracking telemetry, and instant JSON/PNG serialization.
1. Immediate-Mode Canvas vs. DOM/SVG Nodes
Immediate-Mode Performance: Traditional DOM/SVG canvas implementations suffer from layout thrashing and high garbage collection overhead once node counts exceed 500. MindMapper utilizes raw HTML5 2D Canvas context (ctx) with direct draw call pipelining.
Zero-Layout Overhead: Because elements do not instantiate heavy DOM nodes, memory overhead scales as O(1) per frame with predictable sub-millisecond render ticks.
Sub-Pixel Zoom & Pan Matrix: Viewport coordinates are mapped through a 2D affine transformation matrix (x_canvas = (x_screen - panX) / zoom), supporting seamless 0.1x to 5.0x zoom without blurriness.
Device Pixel Ratio (DPR) Scaling: Automatically queries window.devicePixelRatio and rescales the backing store canvas buffer to ensure razor-sharp rendering on Retina and 4K displays.
2. Superellipse Squircles & Text Typography
Superellipse Geometry (Lamé Curves): Rather than crude pill shapes or sharp rectangles, neurons are rendered as smooth squircles following |x/a|^n + |y/b|^n = 1 (with n=4), producing an organic, Apple-like visual feel.
Dynamic Multi-Line Text Wrapping: Text stems are measured line-by-line via ctx.measureText() with word boundary tokenization, dynamically expanding the neuron bounding box with uniform horizontal and vertical padding.
Variable Stroke Hierarchies: Main root nodes feature 4.0px bold strokes with glowing drop-shadow halos, while secondary branches scale down to 2.5px to establish immediate visual depth.
Interactive Hit Testing: Point-in-polygon and distance-to-curve calculations enable instant cursor hovering, drag selection, and double-click inline text editing.
3. Synaptic Bezier Routing & Magnetic Anchors
Cubic Bezier Trajectories: Connection lines compute dynamic control points (P1, P2) proportional to node separation distance, generating organic S-curves that never look rigid or robotic.
Magnetic Anchor Intersection Solver: Calculates exact boundary intersection coordinates along the squircle perimeter so connecting arrows terminate cleanly at the node edge without clipping borders.
Directional Arrowhead Vectors: Arrowheads are drawn using rotational vector geometry (atan2(dy, dx)) with configurable tip angles and arrowhead lengths.
Binding Integrity: Connection objects store startBinding and endBinding element IDs, ensuring that moving any parent neuron dynamically updates all connected synaptic lines in real time.
4. Command-Pattern History & Undo/Redo Engine
Immutable State Snapshotting: HistoryManager maintains dual undoStack and redoStack arrays with a maximum depth limit (e.g., 50 states) to guard against memory ballooning.
Atomic Action Dispatcher: Every mutation (adding neurons, dragging clusters, drawing freehand pen strokes, modifying colors) dispatches a unified history event.
Micro-Batching: High-frequency drag operations batch mouse move events into a single atomic history transaction upon pointer up, preventing history clutter.
Keyboard Shortcut Integration: Full cross-platform keyboard support (Cmd+Z / Ctrl+Z for Undo, Cmd+Shift+Z / Ctrl+Y for Redo) with reactive UI state triggers.
5. Local-First Sovereignty & Zero Telemetry
Zero Cloud Lock-In: All mind maps and sketches live exclusively in the user's local storage or browser IndexedDB database. No personal telemetry or canvas contents are ever transmitted to third-party servers.
Autosave State Machine: Debounced local persistence writes changes within 300ms of inactivity, paired with visual auto-save status indicators.
High-Resolution Raster & JSON Export: One-click export to uncompressed PNG images (with transparent or solid backgrounds) or standard JSON scene graphs for multi-device portability.
REST & Workspace Synchronization: Seamlessly integrates with Epheos cloud workspaces when authenticated, allowing one-click synchronization while preserving local-first offline fallback.
6. Template-Driven Scaffolding Engine
Template Definition Interface (TemplateDefinition): Standardized JSON schema specifying root neurons, categorized branch clusters, synaptic bindings, and preset canvas zoom/pan states.
Blank Canvas Mode: Minimalist empty canvas for unconstrained free-form ideation and rapid sketching.
Brainstorming Template: Pre-wired problem-solving layout organizing Core Goals, Creative Ideas, User Needs, Risks, and Action Items.
System Architecture Blueprint: Pre-configured distributed topology connecting Client Apps, API Gateways, Primary DBs, and Background Workers.
Welcome & Guided Tutorial: Interactive map introducing basic controls (C for connections, N for pen tool, click/double-click) through direct tactile exploration.