# Knowledge Graph Viewer Design

## Goal

Add a local HTML viewer for the generated repository knowledge graph so contributors can inspect nodes, relations, and file ownership without reading raw JSON or Mermaid text.

## Scope

The first version is a local static viewer that reads the generated graph JSON from `.aspirecode/sdd/feature_v1.0.0/knowledge-graph.json` and renders an explorer-style interface.

The first version does not include server-side rendering, image export, or live source rescanning.

## Preferred Experience

Explorer view is the target interaction model.

- left sidebar for search, type filters, and node list
- center canvas for the graph view
- right sidebar for node details and connected relations

## Page Layout

### Header

- page title
- project name and graph version
- node and edge counts
- source file location

### Left Sidebar

- text search by node name
- type filters for `Component`, `Composable`, `Utility`, `TypeExport`, `DocPage`, `RouteGroup`, and `ExamplePage`
- filtered node list for quick selection

### Main Graph Area

- render nodes and edges from `knowledge-graph.json`
- highlight the active node and its first-degree neighbors
- dim unrelated nodes when a filter or selection is active

### Right Sidebar

- selected node name and type
- source file path
- inbound relations
- outbound relations

## Data Source

- input: `.aspirecode/sdd/feature_v1.0.0/knowledge-graph.json`
- output: `.aspirecode/sdd/feature_v1.0.0/knowledge-graph.html`

The viewer reads the existing generated graph only. It does not generate or mutate graph data.

## Rendering Strategy

Use a single self-contained HTML file with embedded CSS and JavaScript.

- no framework dependency required for the first version
- use simple SVG or DOM-based rendering
- keep implementation portable and easy to open in a browser

## Core Interactions

- search for a node by name
- filter by one or more node types
- click a node to inspect details
- click a connected node from the detail panel to jump to it

## Acceptance Criteria

- opening `knowledge-graph.html` in a browser shows the graph without a build step
- viewer loads graph metadata, node count, and edge count from JSON
- viewer supports search and type-based filtering
- viewer supports selecting a node and showing its related edges
- viewer remains usable with the current graph size generated from this repository