Skip to main content

Overview

DecipherIt creates interactive visual mindmaps from your research content, helping you understand relationships, hierarchies, and structure at a glance. Using CrewAI agents and the react-mindmap-visualiser library, it transforms complex research into intuitive visual diagrams.
Mindmaps are generated on-demand with adaptive depth (2-5 levels) based on content complexity.

How It Works

1

Content Retrieval

All research content is fetched from the vector database.Data Collection:
  • All chunks retrieved from Qdrant by notebook ID
  • Content sorted by chunk index
  • Assembled into complete research text
  • Passed to mindmap generation crew
Implementation: backend/agents/mindmap_agent.py:144-161
2

Content Analysis

The Content Analyzer agent identifies hierarchical themes and relationships.Analysis Process:
  • Determines appropriate depth (2-5 levels) based on complexity
  • Identifies ONE main central topic
  • Breaks down into primary categories (3-6)
  • Finds secondary subtopics (2-5 per category)
  • Extracts detailed aspects if warranted
  • Creates clear parent-child relationships
Implementation: backend/agents/mindmap_agent.py:29-58
3

Structure Creation

The Mindmap Creator agent builds the hierarchical node structure.Node Structure:
  • Root node with single main topic
  • Unique IDs for all nodes (“root”, “1”, “2”, etc.)
  • Text labels (1-4 words each)
  • Nested arrays for child nodes
  • Empty arrays [] for leaf nodes
Implementation: backend/agents/mindmap_agent.py:60-133
4

Visual Rendering

The mindmap is rendered using react-mindmap-visualiser.Rendering Features:
  • Color-coded nodes by level
  • Expandable/collapsible branches
  • Pan and zoom controls
  • Responsive layout
  • Interactive exploration
Implementation: client/components/notebook/visual-mindmap.tsx:21-108

Generating Mindmaps

  1. Navigate to your processed notebook
  2. Click the Mindmap tab
  3. Click Generate Mindmap button
  4. Wait 1-3 minutes for processing
  5. Interactive mindmap appears when ready
The page automatically polls for completion every 3 seconds.

Mindmap Structure

Adaptive Depth Levels

Mindmaps automatically adapt to content complexity:
Example: Brief article or single document
Main Topic (root)
├─ Category A
│  ├─ Subtopic 1
│  └─ Subtopic 2
├─ Category B
│  ├─ Subtopic 3
│  └─ Subtopic 4
└─ Category C
   ├─ Subtopic 5
   └─ Subtopic 6
Characteristics:
  • Clear, focused topics
  • Limited sub-themes
  • Straightforward relationships

Technical Implementation

CrewAI Agent Configuration

def get_mindmap_crew():
    # Content Analyzer
    content_analyzer = Agent(
        name="Content Analyzer",
        role="Research Content Analyst",
        goal="Analyze research to identify main themes and hierarchical relationships up to 5 levels deep",
        backstory="""You are an expert content analyst who excels at 
                     breaking down complex research into logical hierarchical 
                     structures and identifying key relationships between 
                     concepts at multiple levels of detail.""",
        llm=llm,
        verbose=True
    )
    
    # Mindmap Creator
    mindmap_creator = Agent(
        name="Mindmap Creator",
        role="Mindmap Specialist",
        goal="Create final mindmap structure as nested dictionary with proper hierarchical relationships",
        backstory="""You are a mindmap specialist who transforms analyzed 
                     content into well-organized nested dictionary formats 
                     with clear hierarchical relationships and logical flow.""",
        llm=llm,
        verbose=True
    )
    
    return Crew(
        agents=[content_analyzer, mindmap_creator],
        tasks=[analyze_content_task, create_mindmap_task],
        process=Process.sequential,
        verbose=True,
    )
Source: backend/agents/mindmap_agent.py:8-141

Node Structure Format

class SimpleMindmapStructure(BaseModel):
    mindmap: Dict[str, Any]  # Nested node structure
    title: str               # Mindmap title
    description: str         # Brief description

# Example node structure:
{
    "mindmap": {
        "id": "root",
        "text": "Main Research Topic",
        "display": {"block": True},
        "nodes": [
            {
                "id": "1",
                "text": "Category A",
                "nodes": [
                    {
                        "id": "2",
                        "text": "Subtopic 1",
                        "nodes": []
                    },
                    {
                        "id": "3",
                        "text": "Subtopic 2",
                        "nodes": []
                    }
                ]
            },
            {
                "id": "4",
                "text": "Category B",
                "nodes": []
            }
        ]
    },
    "title": "Research Topic Title",
    "description": "Brief description"
}
Source: backend/models/mindmap_models.py

Analysis Task Configuration

analyze_content_task = Task(
    description="""
    Analyze the research content and identify hierarchical themes with 
    appropriate depth (up to 5 levels):
    
    - Level 1: ONE main central topic/theme (the overarching subject)
    - Level 2: Primary categories under the main topic (3-6 major categories)
    - Level 3: Secondary subtopics under each category (2-5 per category)
    - Level 4: Detailed aspects (if content warrants it, 2-4 per subtopic)
    - Level 5: Specific details (only if highly detailed content, 1-3 per aspect)
    
    Determine the appropriate depth based on content complexity:
    - Simple content: 2-3 levels
    - Moderate content: 3-4 levels
    - Complex content: 4-5 levels
    
    Create a hierarchical breakdown with:
    - ONE main topic at the root level that encompasses the entire research
    - Concise labels (1-4 words each)
    - Logical grouping of related concepts under the main topic
    - Appropriate depth based on content richness
    - Clear parent-child relationships
    """,
    expected_output="""A hierarchical breakdown with appropriate depth 
                       (2-5 levels) based on content complexity, with concise 
                       labels and clear relationships.""",
    agent=content_analyzer
)
Source: backend/agents/mindmap_agent.py:29-58

Visual Rendering

React Component Implementation

export function VisualMindmap({ mindmapData }: VisualMindmapProps) {
  const treeData = useMemo(() => {
    const getBlockStyleForLevel = (level: number): BlockNodeStyle => {
      switch (level % 5) {
        case 0: return "default";
        case 1: return "info";
        case 2: return "success";
        case 3: return "warn";
        case 4: return "danger";
        default: return "default";
      }
    };
    
    const processTreeNode = (node: TreeNode, level: number = 0): TreeNode => {
      return {
        id: node.id || `node-${Math.random()}`,
        text: node.text || "Unknown",
        display: {
          block: true,
          blockStyle: getBlockStyleForLevel(level),
        },
        nodes: node.nodes?.map(childNode => 
          processTreeNode(childNode, level + 1)
        ) || [],
      };
    };
    
    return processTreeNode(mindmapData.mindmap as unknown as TreeNode);
  }, [mindmapData]);
  
  return (
    <div className="w-full h-[700px] bg-gradient-to-br from-slate-50 to-slate-100">
      <Mindmap json={treeData} />
    </div>
  );
}
Source: client/components/notebook/visual-mindmap.tsx:21-108

Color-Coded Levels

Nodes are automatically color-coded by depth:

Level 0

Default - Root node (main topic)

Level 1

Info - Primary categories (blue)

Level 2

Success - Subtopics (green)

Level 3

Warn - Details (yellow)

Level 4

Danger - Specifics (red)

Status Management

Client-Side State

const [mindmap, setMindmap] = useState<string | null>(
  initialMindmap || null
);
const [isGenerating, setIsGenerating] = useState(false);

// Status values:
// - null: Not generated yet
// - "IN_PROGRESS": Currently generating
// - "ERROR": Generation failed
// - JSON string: Mindmap data (success)
Source: client/components/notebook/notebook-polling.tsx:220-223

Polling Implementation

useEffect(() => {
  if (mindmap !== "IN_PROGRESS") return;
  
  const pollInterval = setInterval(async () => {
    const response = await fetch(`/api/notebooks/${notebookId}`);
    const notebook = await response.json();
    const newMindmap = notebook.output?.mindmap;
    
    if (newMindmap && newMindmap !== "IN_PROGRESS") {
      setMindmap(newMindmap);
      
      if (newMindmap === "ERROR") {
        toast.error("Mindmap generation failed");
      } else {
        toast.success("Mindmap ready!");
      }
    }
  }, 3000);
  
  return () => clearInterval(pollInterval);
}, [mindmap, notebookId]);
Source: client/components/notebook/notebook-polling.tsx:226-268

Mindmap Quality Features

Adaptive Complexity

Depth automatically adjusts to content complexity - simple topics get simpler maps.

Concise Labels

1-4 word labels keep the mindmap clean and readable at any zoom level.

Logical Grouping

Related concepts naturally grouped under common parent nodes.

Visual Hierarchy

Color coding and spatial layout make hierarchy immediately apparent.

Use Cases

Use mindmaps to:
  • Quickly grasp research organization
  • Identify main themes at a glance
  • Understand topic relationships
  • See content hierarchy visually
Mindmaps help with:
  • Creating presentation outlines
  • Explaining complex topics visually
  • Showing research breadth
  • Organizing talking points
Visual learning through:
  • Spatial understanding of topics
  • Progressive detail exploration
  • Pattern recognition
  • Memory aids via visualization
Mindmaps reveal:
  • Topic coverage gaps
  • Areas needing deeper research
  • Connection opportunities
  • Content balance issues

Interactive Features

Pan & Zoom

Click and drag to pan, scroll to zoom for exploring large mindmaps.

Expand/Collapse

Click nodes to show or hide their children for focused exploration.

Responsive Layout

Mindmap adapts to screen size for mobile and desktop viewing.

Performance Optimizations

Memoized Processing

Tree data processing is memoized to prevent unnecessary recalculations.

Efficient Rendering

react-mindmap-visualiser uses SVG for crisp, performant rendering at any scale.

Progressive Loading

Polling updates UI progressively without blocking interactions.

Smart Validation

Pydantic models ensure valid structure before rendering attempts.

API Endpoint

Generate Mindmap

POST /api/notebooks/[id]/mindmap

// Response
{
  "message": "Mindmap generation started"
}

// Database updates to "IN_PROGRESS"
// Backend processes asynchronously
// Poll GET /api/notebooks/[id] for completion
Implementation: client/app/api/notebooks/[id]/mindmap/route.ts

Best Practices

For Best Mindmaps:
  • Generate after research is fully processed
  • Use zoom to explore different detail levels
  • Screenshot or export for external use
  • Compare with summary to understand organization
  • Use for identifying follow-up research areas

Limitations

  • AI-Interpreted Structure: Organization reflects AI’s interpretation of themes
  • Depth Variation: Some branches may be deeper than others based on content
  • Label Brevity: 1-4 word limit may oversimplify complex concepts
  • Generation Time: 1-3 minutes typical, varies with content length
  • Static Output: Mindmap doesn’t update when content changes

Troubleshooting

If mindmap lacks detail:
  • Content may be too brief for deep analysis
  • Try adding more sources
  • Ensure sources have substantial content
  • Consider regenerating for different interpretation
If mindmap is overwhelming:
  • Use collapse feature to simplify view
  • Focus on specific branches
  • Zoom in to readable level
  • Content may be very comprehensive (expected)
If generation shows ERROR:
  • Click “Try Again” to regenerate
  • Check that research processed successfully
  • Verify notebook has content
  • Contact support if persists

AI Summaries

Read detailed research summary

FAQ Generation

Explore auto-generated questions

Interactive Q&A

Ask specific questions about topics

Build docs developers (and LLMs) love