How joemattathil/interactive-mindmap works
This repository is a self-contained, browser-only mindmap application with no backend, build step, or external services.
Overall shape
The app is split into three static files:
• index.html provides the page shell: toolbar, dialogs/modals, and the container where the mindmap is displayed.
• mindmap.css owns all visual styling.
• mindmap.js contains the entire application behavior: state, rendering, interaction handling, layout, search, import/export, and mode toggles.
Architecturally, this is a single-client application where the JavaScript layer is the system of record for the mindmap model and UI state.
Main subsystems
1) UI shell and controls
index.html defines the user-facing controls that drive the app:
• add root node
• auto-align
• auto-color-by-level toggle
• save/load JSON
• search input
• edit/add/delete actions via modals/context menu
This layer is mostly structural; it delegates behavior to mindmap.js.
2) Mindmap state and data model
The core data lives in JavaScript as an in-memory hierarchy of nodes. From the README, each node stores:
• title/text
• description
• position
• hierarchy relationship
• collapse/expand state
• selected color
• versioned metadata in saved files
The app also maintains global view state such as:
• zoom level
• pan offset
• search query/results
• auto-color mode on/off
• editing/selection state
This separation is important: node data describes the map itself, while view state controls how the map is presented on screen.
3) Layout and rendering
The app supports an auto-aligned hierarchical layout. That implies a layout routine in mindmap.js that:
• walks the node hierarchy
• computes positions for visible nodes
• respects collapse/expand state
• updates the displayed arrangement after structural changes
Rendering is dynamic and responsive to state changes such as:
• adding/removing nodes
• dragging nodes
• expanding/collapsing branches
• switching auto-color mode
• changing zoom/pan
• search highlighting
mindmap.css provides the visual treatment for nodes, links, highlights, menus, and modals.
4) Interaction handling
mindmap.js also acts as the interaction controller. It handles:
• drag a node to reposition it
• drag empty canvas to pan
• mouse wheel to zoom around cursor
• double-click to inline edit node title
• right-click for contextual add/edit/delete actions
• keyboard Escape to dismiss modal/context menu
• search highlighting across title and description
This is the primary behavioral boundary of the app: all direct user input is translated into mutations of the in-memory model or view state.
5) Branch visibility and hierarchy management
The mindmap is a tree/forest of nodes, not a flat canvas. The app supports:
• multiple root nodes
• parent/child creation
• collapse/expand of branches
• auto-alignment based on hierarchy depth
Because of this, the render pipeline must distinguish between:
• structural nodes that exist in the model
• visible nodes that should be laid out and drawn
• hidden descendants under collapsed branches
6) Search and highlighting
Search is a read-only filter/highlight layer over the model:
• matches are based on node title and description
• matching nodes are visually highlighted
• search does not appear to alter the saved data model directly
This is a UI overlay on top of the hierarchy, not a separate index or service.
7) Persistence boundary: JSON export/import
Persistence is entirely file-based and browser-local.
• Save serializes the current mindmap into JSON.
• Load reads a JSON file back into the app.
The saved JSON includes:
• version
• timestamp
• autoColorByHierarchy state
• full nodes[] data with positions, hierarchy, text, description, collapse state, and user color
This makes JSON the main interchange boundary for the application. There is no server database or remote API.
Important behavior boundaries
Auto color by level
This is a rendering mode, not a data rewrite mode.
• When enabled, node colors are derived from depth level using a repeating palette.
• When disabled, the user-chosen per-node color is shown.
• Saved node colors are still preserved in JSON regardless of mode.
So the app distinguishes between stored color data and active rendering rules.
Layout vs manual positioning
The app supports both:
• manual movement by dragging nodes
• automatic reflow via auto-align
That means the model must preserve coordinates while also being able to recompute them from hierarchy when requested.
Node content vs presentation
Node titles/descriptions are content. Colors, collapse state, zoom/pan, search highlights, and auto-color mode are presentation or interaction state.
Runtime and deployment
• Runs directly in a browser.
• No compilation or bundling is required.
• Can be opened as a local file or served statically.
• No external dependencies are indicated.
How to think about the architecture diagram
A useful diagram would show:
1. The browser as the runtime container.
2. index.html as the static UI shell.
3. mindmap.js as the central controller/state engine.
4. mindmap.css as the styling layer.
5. A bidirectional flow between the user and mindmap.js:
- user actions in
- state updates out
- DOM/CSS rendering refreshed
6. A file-based import/export boundary for JSON persistence.
7. The node hierarchy as the central data structure, with layout, search, color mode, and collapse state all layered on top of it.
In short, this is a single-page, client-side mindmap editor where one JavaScript module owns both the application model and the interactive behavior, while HTML and CSS provide the shell and presentation.
Main entry points: mindmap.js App Core · index.html Shell · mindmap.css Styles
Components 12
Runtime
Browser-only execution environment
- Browser · Executes the app directly with no backend or build step
Presentation
Static shell and visual styling
Application Logic
State, interaction, layout, and rendering
- App Core · Single script owning state, behavior, layout, rendering, and persistence
mindmap.js - State · Zoom, pan, selection, search, edit mode, and color mode
- Mindmap · In-memory node tree with titles, descriptions, positions, colors, and collapse state
- Layout · Computes hierarchical positions for visible nodes
- Render · Updates the canvas, nodes, links, and visual highlights
- Interaction · Drag, pan, zoom, edit, context menu, and keyboard actions
- Search · Matches titles and descriptions and marks results in the view
Persistence
Local JSON import/export boundary
- JSON I/O · Loads and saves versioned mindmap data in browser-local JSON files
- JSON File · Serialized mindmap snapshot exchanged through import/export
Connections 17
- Browser → Shell: loads · The browser opens the static page shell
- Browser → Styles: applies · The browser uses the stylesheet for presentation
- Browser → App Core: runs · The browser executes the app logic directly
- Shell → App Core: hosts · The shell provides the DOM container and controls used by the script
- App Core → State: owns · The script maintains global view state
- App Core → Mindmap: stores · The script is the system of record for the mindmap model
- Interaction → State: mutates · User actions update selection, zoom, pan, and edit state
- Interaction → Mindmap: mutates · Editing, add, delete, drag, and collapse operations change the hierarchy
- Mindmap → Layout: feeds · Visible hierarchy drives position calculation
- Layout → Render: updates · Computed positions are drawn into the view
- State → Render: drives · View state affects highlights, transforms, and mode toggles
- Search → Render: highlights · Search results are overlaid in the rendered view
- App Core → Interaction: handles · The app script listens for all direct user interactions
- App Core → Search: filters · Search logic scans node titles and descriptions
- App Core → JSON I/O: imports/exports · The script serializes and deserializes mindmap JSON
- JSON I/O → JSON File: reads/writes · Persistence happens through local JSON files
- Styles → Render: styles · Styling shapes the rendered nodes, menus, and dialogs