Skip to content

frontend knowledge_graph

Jump to bottom
aakash-anko edited this page Jul 1, 2026 · 2 revisions

frontend / Knowledge Graph UI

The Next.js knowledge graph dashboard renders the knowledge-graph.json produced by graph/knowledge_graph_export.py as an interactive, explorable graph. It lives in frontend/src/app/knowledge-graph/ and frontend/src/components/kg/.

Key Concepts

Term Definition Example
Structural view Hierarchical, layer-based visualization of files, classes, and functions grouped by module. Default view when the graph has layers
Knowledge view Flat force-directed view of the raw node/edge graph. Useful for exploring all relationships without hierarchy
layer A detected module shown as a cluster in the overview. layer:ingestion
container An expandable folder group inside a layer detail view. container:src/codewalk/ingestion
persona A viewing preset that controls how much technical detail is shown. experienced, junior, non-technical

Entry points

frontend/src/app/knowledge-graph/page.tsx

Server component that wraps KnowledgeGraphClient in a Suspense boundary with a loading fallback.

frontend/src/app/knowledge-graph/KnowledgeGraphClient.tsx

Client-side orchestrator:

  1. Reads repoPath from the URL query string (useSearchParams).
  2. Calls loadKnowledgeGraph(repoPath) to fetch the JSON.
  3. Optionally fetches /api/diff-overlay to highlight changed/affected nodes.
  4. Renders the chosen view inside DashboardShell.
  5. Lazily loads the CodeViewer when a node requests source inspection.

If the user navigates to a different repoPath, the cached graph is cleared and reloaded.

Dashboard shell and controls

frontend/src/components/kg/DashboardShell.tsx

Provides the chrome around the graph: header, view-mode switch, search bar, sidebar, tool modals, and onboarding.

Key UI areas:

  • Project title — graph.project.name.
  • View toggle — Structural / Knowledge (Structural is disabled when the graph has no layers).
  • Diff toggle — enables diff overlay when changed/affected nodes exist.
  • Layer legend — color key for modules.
  • Export menu — JSON, SVG, PNG.
  • Path Finder button — opens dependency-path search.
  • Theme picker — switches color themes.
  • Sidebar tabs — Info (NodeInfo when selected, else ProjectOverview) and Files (FileExplorer).
  • Keyboard shortcuts — ? for help, Escape to close panels, / to focus search, d diff, f filters, e export, p path finder, arrow keys for tour.

View modes

Structural view (default)

Implemented by frontend/src/components/kg/GraphView.tsx.

Navigation levels:

  1. Overview — layer clusters as large nodes, aggregated inter-layer edges. Layout computed by the ELK web worker (applyElkLayoutWorker).
  2. Layer detail — files grouped into expandable folder containers derived by deriveContainers. Backend positions are used when available; otherwise ELK lays out containers and ungrouped nodes.
  3. File flow — alternate flat view of files within the active layer with import edges.

Clicking a layer cluster drills into that layer. Clicking empty canvas or using Escape navigates back to overview. Containers can be expanded/collapsed and auto-expand when zoomed past 1x.

Knowledge view

Implemented by frontend/src/components/kg/KnowledgeGraphView.tsx.

A flat force-directed rendering of nodes and edges. Uses backend pre-computed x/y positions when present; otherwise falls back to a client-side force layout. Supports three sub-filters:

  • Files — show only file nodes
  • Functions — show only function/method/class nodes
  • Files + Funcs — show both

Node-category filters

frontend/src/components/kg/FilterPanel.tsx exposes seven category toggles:

Category Typical node types
Code file, function, class, method, module
Config config
Docs document
Infrastructure service, resource, pipeline
Data table, endpoint, schema
Domain domain, flow, step
Knowledge article, entity, topic, claim, source

The mapping is defined in frontend/src/lib/kg/types.ts (NODE_TYPE_TO_CATEGORY).

Detail-level toggle

  • File — show files only.
  • Class — expand classes (via contains edges) and optionally functions.

"Show functions in class view"

When detail level is Class, a checkbox controls whether standalone functions are also expanded from files, or only classes.

Persona selector

frontend/src/components/kg/PersonaSelector.tsx lets the user choose:

Persona Effect
Experienced Show all node types.
Junior Same technical detail; tour/learn mode is surfaced in the mobile info pane.
Non-Technical Hides function and class sub-file nodes, leaving files, modules, and knowledge nodes.

Path Finder

frontend/src/components/kg/PathFinderModal.tsx searches dependency paths between two nodes.

  • Modes: Shortest path (BFS) or All simple paths (DFS with maxDepth: 6, maxPaths: 20).
  • Pickers: searchable dropdown of file, module, class, and function nodes.
  • Results show each hop; clicking a hop selects the node, navigates to its layer, and closes the modal.

Export menu

frontend/src/components/kg/ExportMenu.tsx offers three exports:

Format Behavior
JSON Downloads the raw knowledge-graph.json object as knowledge-graph.json.
SVG Renders the current React Flow viewport to SVG and downloads it.
PNG Renders to SVG, converts to a PNG data URL, and downloads it.

Code viewer

frontend/src/components/kg/CodeViewer.tsx displays source for the currently selected node.

  • Fetches /api/file-content?path={filePath}.
  • Highlights syntax with prism-react-renderer using vsDark.
  • Highlights the node's lineRange.
  • Can be expanded to a centered modal or collapsed to a 40vh bottom pane.

File explorer sidebar

frontend/src/components/kg/FileExplorer.tsx builds a directory tree from node.filePath. Single-click selects and navigates to the node; double-click opens the code viewer.

Heuristic tour / onboarding

Onboarding overlay

frontend/src/components/kg/OnboardingOverlay.tsx shows on first visit (stored via localStorage key codewalk-kg-onboarding). It walks through welcome, layers/containers, search/path finder, and keyboard shortcuts.

Heuristic tour

The tour steps come from graph.tour in knowledge-graph.json. When active, the viewport auto-fits to highlighted nodes and CustomNode renders them with an accent pulse ring. Left/right arrows step backward/forward.

Mobile layout

frontend/src/components/kg/MobileLayout.tsx replaces the desktop shell on narrow viewports:

  • Bottom tab navigation: Graph / Info / Files.
  • A header hamburger opens MobileDrawer.
  • MobileDrawer exposes Filters, Path Finder, Export SVG/PNG, and Shortcuts.

frontend/src/components/kg/useIsMobile.ts detects mobile widths.

Edge styling

Edges use the CSS variable var(--kg-accent) by default.

  • Unselected: solid accent lines, strokeWidth: 2 (or thicker when aggregated).
  • Connected to selected node: thicker (strokeWidth: 3), fully opaque, and animated.
  • Non-selected when a node is active: dimmed to opacity: 0.12 so the selected node's neighborhood stands out.

Diff overlay

When /api/diff-overlay returns changedNodeIds and affectedNodeIds:

  • DiffToggle appears in the header showing counts.
  • Toggling diff mode highlights changed nodes with a red ring and affected nodes with an accent ring.
  • Unrelated nodes are faded.
  • Press d to toggle.

Repo selection

The active repo is selected in this order:

  1. repoPath query parameter: /knowledge-graph?repoPath=/abs/path/to/repo
  2. CODEWALK_REPO_PATH environment variable (used by scripts/run-ui-for-repo.sh)
  3. Fallback to the Next.js process cwd and its parent

KnowledgeGraphClient compares the resolved path against graph.project.repoPath and reloads when they differ.

Component index

Page-specific components (frontend/src/app/knowledge-graph/_components/)

Component Purpose
NetworkGraph.tsx Primary React Flow structural graph (replaces the old page-level GraphView).
FolderGraph.tsx Folder-tree / file-level graph view.
DependencyView.tsx Dependency-focused subviews.
LayerTree.tsx Module / layer tree sidebar.
LayerDetail.tsx Expanded layer detail panel.
NodeDetailPanel.tsx Selected node metadata + source preview.
CodePreview.tsx Source peek for selected node.
SettingsPanel.tsx Filters, themes, export, search settings.
KineticNode.tsx Shared node renderer.
layout.worker.ts Web Worker wrapper for ELK layout.

Shared components (frontend/src/components/kg/)

Component Purpose
CustomNode.tsx Default node card with type badge, summary, selection/tour/diff states.
LayerClusterNode.tsx Layer cluster node used in structural overview.
ContainerNode.tsx Expandable folder container in layer detail view.
LayerLegend.tsx Color legend for layers/modules.
SearchBar.tsx Fuzzy node search.
NodeInfo.tsx Sidebar details for the selected node.
ProjectOverview.tsx Sidebar project summary when no node is selected.
Breadcrumb.tsx Navigation breadcrumb for overview / layer / node.
NodeTooltip.tsx Hover tooltip.
ThemePicker.tsx Theme switcher.
WarningBanner.tsx Displays layout issues from the ELK worker.
useKeyboardShortcuts.ts Global keyboard shortcut handling.

The app-level navigation shell is frontend/src/components/KineticShell.tsx; it is separate from the in-page graph sidebars.

Clone this wiki locally