# joemattathil/interactive-mindmap architecture

> Architecture diagram of the GitHub repository joemattathil/interactive-mindmap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joemattathil/interactive-mindmap
- Repository: https://github.com/joemattathil/interactive-mindmap

## Overview

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`](https://github.com/joemattathil/interactive-mindmap/blob/HEAD/mindmap.js) (App Core), [`index.html`](https://github.com/joemattathil/interactive-mindmap/blob/HEAD/index.html) (Shell), [`mindmap.css`](https://github.com/joemattathil/interactive-mindmap/blob/HEAD/mindmap.css) (Styles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Runtime"
  browser(("Browser<br/>runtime"))
end

subgraph "Presentation"
  index_html["Shell<br/>static page<br/>[index.html]"]
  mindmap_css["Styles<br/>css<br/>[mindmap.css]"]
end

subgraph "Application Logic"
  mindmap_js["App Core<br/>javascript<br/>[mindmap.js]"]
  state[("State")]
  tree[("Mindmap<br/>hierarchy")]
  layout["Layout<br/>auto-align"]
  render["Render<br/>dom update"]
  input["Interaction<br/>event handling"]
  search["Search<br/>highlighting"]
end

subgraph "Persistence"
  io["JSON I/O<br/>persistence"]
  file["JSON File<br/>saved data"]
end

browser -->|"loads"| index_html
browser -->|"applies"| mindmap_css
browser -->|"runs"| mindmap_js
index_html -->|"hosts"| mindmap_js
mindmap_js -->|"owns"| state
mindmap_js -->|"stores"| tree
input -->|"mutates"| state
input -->|"mutates"| tree
tree -->|"feeds"| layout
layout -->|"updates"| render
state -->|"drives"| render
search -->|"highlights"| render
mindmap_js -->|"handles"| input
mindmap_js -->|"filters"| search
mindmap_js -->|"imports/exports"| io
io -->|"reads/writes"| file
mindmap_css -->|"styles"| render

click index_html "https://github.com/joemattathil/interactive-mindmap/blob/main/index.html"
click mindmap_css "https://github.com/joemattathil/interactive-mindmap/blob/main/mindmap.css"
click mindmap_js "https://github.com/joemattathil/interactive-mindmap/blob/main/mindmap.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class browser toneBlue
class index_html,mindmap_css toneAmber
class mindmap_js,state,tree,layout,render,input,search toneMint
class io,file toneRose
```

## Components

### Runtime

Browser-only execution environment

- **Browser**: runtime · Executes the app directly with no backend or build step

### Presentation

Static shell and visual styling

- [Shell](https://github.com/joemattathil/interactive-mindmap/blob/HEAD/index.html): static page · Page structure, toolbar, dialogs, and app container · `index.html`
- [Styles](https://github.com/joemattathil/interactive-mindmap/blob/HEAD/mindmap.css): css · Visual rules for nodes, links, menus, modals, and highlights · `mindmap.css`

### Application Logic

State, interaction, layout, and rendering

- [App Core](https://github.com/joemattathil/interactive-mindmap/blob/HEAD/mindmap.js): javascript · Single script owning state, behavior, layout, rendering, and persistence · `mindmap.js`
- **State**: ui state · Zoom, pan, selection, search, edit mode, and color mode
- **Mindmap**: hierarchy · In-memory node tree with titles, descriptions, positions, colors, and collapse state
- **Layout**: auto-align · Computes hierarchical positions for visible nodes
- **Render**: dom update · Updates the canvas, nodes, links, and visual highlights
- **Interaction**: event handling · Drag, pan, zoom, edit, context menu, and keyboard actions
- **Search**: highlighting · Matches titles and descriptions and marks results in the view

### Persistence

Local JSON import/export boundary

- **JSON I/O**: persistence · Loads and saves versioned mindmap data in browser-local JSON files
- **JSON File**: saved data · Serialized mindmap snapshot exchanged through import/export

## Connections

- 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
