View source for Concept Map View - Specification

= Concept Map View — Specification =

== 1. Purpose ==
The concept map is a visual, zoomable representation of the knowledge base. It lets users see the structure of Harivulagam — the six pillars, the entries within them, and the connections between them — as a navigable space rather than a list.

It is the Deep world made visible: the layer where connections become apparent.
----

== 2. Core Interaction Model ==
The map behaves like a geographic map, not like a slideshow. Users are free to pan, zoom, and click.
{| class="wikitable"
!Interaction
!Behavior
|-
|Pan
|Click and drag anywhere on the canvas
|-
|Zoom
|Scroll wheel, pinch gesture, or double-click to zoom in
|-
|Zoom to fit
|Button to reset view to show all pillars
|-
|Click a node
|Opens a side panel with the entry summary and a link to the full page
|-
|Hover a node
|Shows the entry title and connection type
|-
|Click a connection line
|Shows the two entries it links and the connection type
|-
|Search
|Highlights matching nodes on the map
|-
|Filter by pillar
|Dims nodes not in the selected pillar
|-
|Filter by connection type
|Shows only #Historical Influence, #Structural Resonance, or #Intuitive Connection
|}
Minimum zoom: full map (all six pillars visible)

Maximum zoom: individual entry detail
----

== 3. Visual Hierarchy ==
The map has three zoom levels, each revealing more detail. This follows the geographic metaphor from your earlier vision.

=== Level 1 — Pillars (Continents) ===
At the lowest zoom, only the six pillars appear as large labeled regions:

* Epics & Scriptures
* Science & Quantum
* Siddhas & Lineages
* Dream Insights
* Historical Events
* Synthesis

Each pillar is a distinct color and occupies its own zone on the canvas. No individual entries are visible at this level.

=== Level 2 — Entries (Countries and Cities) ===
As the user zooms in, individual entries appear within each pillar. They are shown as nodes — circles or small cards — with their titles visible.

Connections between entries begin to appear as lines. At this level, the user can see which entries are well-connected and which are isolated.

=== Level 3 — Detail (Streets) ===
At the highest zoom, nodes expand to show:

* Entry title
* A short summary (one or two sentences)
* Tags (pillar, connection types)
* A link to the full entry
* A list of connected entries

This is the deepest level before the user leaves the map and opens the full page.
----

== 4. Layout Logic ==
The map is not a geographic map. It is a force-directed graph or a manually arranged concept map, depending on preference.

=== Option A — Force-Directed Layout ===
Nodes repel each other, connections pull them together. The layout emerges from the data.

Pros: Reveals clusters naturally; new entries find their place automatically.

Cons: Layout can shift when data changes; less stable for returning users.

=== Option B — Manual Layout ===
Each pillar occupies a fixed zone. Entries are placed within their pillar by the editor.

Pros: Stable, predictable, and curated.

Cons: Requires manual placement as the base grows.

=== Recommendation ===
Use Option B for pillars (fixed zones, so the map feels stable) and Option A for entries within each pillar (so new entries find their place without constant manual work).

This gives you stability at the top level and flexibility at the detail level.
----

== 5. Connection Types — Visual Encoding ==
Connections between entries are shown as lines. The type of connection determines the line style.
{| class="wikitable"
!Connection type
!Line style
!Color
|-
|#Historical Influence
|Solid line
|Dark blue
|-
|#Structural Resonance
|Dashed line
|Teal
|-
|#Intuitive Connection
|Dotted line
|Amber
|}
This means a user can see, at a glance, what kind of connection they are looking at — without reading a label.

A legend is always visible in a corner of the map.
----

== 6. Node Visual Encoding ==
Nodes vary by pillar (color) and status (shape or border).
{| class="wikitable"
!Attribute
!Encoding
|-
|Pillar
|Fill color (one per pillar)
|-
|Stub entry
|Dashed border
|-
|Complete entry
|Solid border
|-
|Witness record (dream insight)
|Distinct shape (e.g., diamond)
|-
|Connection article (main site)
|Double border
|}
This lets users see, without clicking, what kind of content they are looking at.
----

== 7. Side Panel (On Click) ==
When a user clicks a node, a side panel opens with:

# Entry title
# Pillar it belongs to
# Short summary (pulled from the entry)
# Connection type tags (if it is a connection article)
# List of connected entries (clickable)
# "Read full entry" button — opens the wiki page or connection article
# "Show on map" button — centers the map on this node

The side panel does not replace the map. It sits alongside it, so the user never loses their place.
----

== 8. Technical Implementation ==
Based on our earlier discussion, the recommended stack is:
{| class="wikitable"
!Component
!Tool
|-
|Map engine
|Leaflet with <code>L.CRS.Simple</code> (pixel coordinates, not lat/lng)
|-
|Zoom-based layer visibility
|<code>leaflet-zoomshowhide</code>
|-
|Node rendering
|SVG or HTML markers
|-
|Connection lines
|SVG paths overlaid on the Leaflet canvas
|-
|Data source
|JSON exported from the wiki (or a lightweight API)
|-
|Search
|Client-side filtering of node data
|-
|Embedding
|Standalone page at <code>harivulagam.com/map</code>
|}
Why Leaflet and not a graph library?

Because you already understand the Leaflet model from your Sozi/Inkscape experience, and because <code>L.CRS.Simple</code> lets you treat the canvas as a conceptual space rather than a geographic one. The same tool that shows continents and cities can show pillars and entries.

If you later want a pure graph view (force-directed), you can add a second view using D3.js. But Leaflet gets you the Google Maps-like feel you described.
----

== 9. URL Structure ==
Every view on the map should have a shareable URL:
{| class="wikitable"
!View
!URL pattern
|-
|Full map
|<code>harivulagam.com/map</code>
|-
|Single pillar
|<code>harivulagam.com/map?pillar=science</code>
|-
|Single entry
|<code>harivulagam.com/map?entry=lokayata</code>
|-
|Filtered view
|<code>harivulagam.com/map?type=structural</code>
|}
This lets users share specific views and lets you link directly to a map position from a wiki entry or connection article.
----

== 10. Accessibility and Fallbacks ==
Not every user will want to use the map. Some will prefer lists. Some will be on slow connections. Some will use screen readers.

Therefore:

* Every map view has a "List view" toggle that shows the same data as a sortable list.
* All nodes are keyboard-navigable (tab to move, enter to open).
* Node labels are text, not images, so screen readers can read them.
* The map degrades gracefully — if JavaScript is disabled, the list view loads by default.

The map is an enhancement, not a requirement.
----

== 11. What the Map Does Not Do ==
To keep it focused:

* It does not allow editing. Editing happens on the wiki.
* It does not show full article text. It shows summaries and links.
* It does not auto-arrange in real time as you watch. Layout updates when data changes, not on every interaction.
* It does not claim to show all connections — only the ones that have been entered.

The map is a view of the knowledge base, not a separate knowledge base.
----

== 12. Phased Implementation ==
Phase 1 — Static map

* Render the six pillars as fixed zones
* Place 10–20 seed entries manually
* Draw connections as SVG lines
* No interaction beyond pan and zoom

Phase 2 — Interactive map

* Add click-to-open side panel
* Add search and filter
* Add URL parameters for shareable views

Phase 3 — Dynamic map

* Pull entries and connections from the wiki automatically
* Update layout when new entries are added
* Add the list-view toggle and accessibility features

Phase 4 — Integration with open4d.online

* Link map nodes to VR scenes where available
* Allow users to "enter" an era or concept from the map