Graph Visualization

​

Viewing the Skill Graph

​

Accessing the Graph

• Desktop: Background layer behind the skills list panel
• Mobile: “Graph” tab in the tabbed interface
• Shows all skills across all enabled vaults

• Desktop: Sidebar panel (collapsible)
• Mobile: “Graph” section in the tabbed interface
• Shows local graph focused on the current skill

​

Graph Layouts

┌─────────────────────────────────────────────┐
│                                             │
│     [Graph Background - Full Width]         │
│     • Force-directed layout                 │
│     • Vault legend (top-left)               │
│                                             │
│                      ┌──────────────────┐   │
│                      │ Skills List      │   │
│                      │ (floating panel) │   │
│                      └──────────────────┘   │
└─────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│  [Graph] [Vaults]                           │
├─────────────────────────────────────────────┤
│                                             │
│     Graph visualization                     │
│     (full screen when active)               │
│                                             │
└─────────────────────────────────────────────┘

​

Graph Components

​

Node Types

• Shape: Circular
• Color: Vault color (enterprise) or default primary color
• Size: Proportional to number of connections
• Label: Skill name

• Shape: Smaller circular nodes
• Color: Muted color scheme
• Label: Resource filename or title
• Connection: Linked to parent skill

• Shape: Circular
• Color: Relationship-based coloring
• Purpose: Represent skill-to-skill references

​

Vault Legend

┌─────────────────────────────────────────────┐
│ [■] my-vault personal                       │
│ [■] team-vault enterprise                   │
│ [■] default-vault default                   │
└─────────────────────────────────────────────┘

• Color square - Vault color indicator
• Vault name - Display name
• Vault type - personal, enterprise, or default
• Disabled state - Grayed out if vault is disabled

​

Navigating the Graph

​

Mouse/Touch Interactions

• Click and drag empty space to pan the graph
• Touch and drag on mobile devices

• Scroll wheel to zoom in/out (desktop)
• Pinch gesture to zoom (mobile)
• Zoom range: 0.5x to 3x

• Click on a skill node to view details
• Click on a resource node to open the resource
• Hover over nodes to see preview cards (desktop)

• Double-click empty space to reset zoom and center

​

Node Preview Cards

┌─────────────────────────────────────┐
│  [Skill Name]                       │
│  Description preview...             │
│  Vault: my-vault                    │
│  Resources: 5                       │
└─────────────────────────────────────┘

• Skill nodes: Name, description, vault, resource count
• Resource nodes: Filename, type, parent skill
• Auto-hide: Disappears when mouse leaves node

​

Keyboard Navigation

• Tab - Cycle through focusable nodes
• Enter - Select the focused node
• Arrow keys - Pan the graph viewport
• +/- - Zoom in/out
• 0 - Reset zoom to 1x

​

Resource Relationships

​

Parent-Child Connections

• Direct edges - Lines connecting resource to skill
• Proximity - Resources cluster near their parent
• Color coding - Subtle color variation by vault

​

Mention Links

[Skill A] ──mentions──> [Skill B]

• Direct mentions - Explicit [[skill-name]] references in markdown
• Resource mentions - Resources referencing skills
• Bidirectional - Some mentions create two-way links

​

Graph Depth

• Focus node - The current skill (highlighted)
• First-degree connections - Directly mentioned skills and resources
• Second-degree connections - Skills mentioned by first-degree skills (if enabled)

​

Graph Features

​

Force-Directed Layout

• Attraction forces - Pull connected nodes together
• Repulsion forces - Push unconnected nodes apart
• Center gravity - Prevent nodes from drifting too far
• Damping - Gradual settling into stable positions

​

Initial Positioning

• Center bias: Slight left offset (-0.18x) to accommodate skills panel
• Mobile scale: 0.9x initial zoom for better fit

• Centered on the focus skill
• Initial zoom: 1.0x
• Auto-fit: Adjusts to show all connections

​

Responsive Behavior

• Height: Dynamic calculation based on available space
  • Desktop: 75vh (viewport height)
  • Mobile: Minimum 360px
• Width: Full panel width
• Re-render: Automatically resizes on window resize
• Mobile optimization: Simplified rendering for performance

​

Graph States

​

Loading State

┌─────────────────────────────────────────────┐
│                                             │
│          [Loading spinner]                  │
│                                             │
└─────────────────────────────────────────────┘

​

Error State

┌─────────────────────────────────────────────┐
│                                             │
│      Failed to load graph                   │
│                                             │
└─────────────────────────────────────────────┘

​

Empty State

┌─────────────────────────────────────────────┐
│                                             │
│      No skills to display                   │
│                                             │
└─────────────────────────────────────────────┘

​

Performance Considerations

​

Large Graphs

• Virtualization - Only render visible nodes
• LOD (Level of Detail) - Simplify distant nodes
• Debounced physics - Reduce simulation frequency when idle
• Canvas rendering - GPU-accelerated drawing

​

Mobile Optimization

• Lower initial scale - 0.9x vs 1.0x on desktop
• Simplified edges - Thinner lines, fewer decorations
• Touch targets - Larger hit areas for nodes
• Reduced animations - Fewer particle effects

​

Graph Customization

• Vault colors - Set in enterprise vault settings
• Node sizing - Automatic based on connections
• Layout algorithm - Force-directed (no alternatives yet)

​

Use Cases

​

Discovery

• Explore connections between related skills
• Find orphaned skills with no connections
• Identify clusters of related knowledge

​

Navigation

• Jump to skills by clicking nodes
• Trace resource usage across skills
• Follow mention chains to related content

​

Analysis

• Visualize vault distribution by color
• Identify central skills with many connections
• Spot knowledge gaps in sparse areas