# Knowledge Graph Visualization — Concept & Feasibility

**Status:** Concept — under review  
**For discussion with:** Ramon

This document explores the feasibility, functional value, and marketing potential of a knowledge graph visualization for the Ask QIEN KB — inspired by Obsidian's graph view but grounded in richer relationship data.

---

## What Obsidian's graph view does

Obsidian renders a force-directed node graph where each note is a node and each `[[wiki-link]]` between notes is an edge. Nodes cluster by connectivity: heavily cross-referenced notes pull toward the centre, orphaned notes drift to the periphery. The insight it provides is structural — you can see which notes are foundational, which are isolated, and which topics naturally cluster together.

---

## What we could build

We have richer relationship data than Obsidian does. Obsidian only knows about explicit links an author typed into a document. We have four distinct edge types already present in the database:

| Edge type | Source | Description |
|---|---|---|
| **Explicit ticket links** | `knowledge_entry_ticket_links`, `ticket_kb_sources` | KB entries linked to or cited in specific tickets |
| **Semantic similarity** | Vector embeddings (already computed per entry) | Cosine similarity above a threshold = implicit edge, no author required |
| **Usage weight** | `ticket_kb_sources.usage_type` | How many times an entry was retrieved, cited, or expert-selected — a natural edge weight |
| **Tag co-occurrence** | `knowledge_entries.category_tags` | Entries sharing tags form a natural grouping layer |

A `/knowledge/graph` route rendering this as a force-directed graph is a moderate build using a library like `react-force-graph` or `Cytoscape.js`. The underlying data is already in the database — no new data collection is needed.

---

## Functional value

This is not purely cosmetic. A graph view would surface things that are invisible in a flat list:

**Orphan entries.** KB articles with no ticket links and low similarity to anything else. Candidates for review — probably outdated, too narrow, or duplicating something better.

**Hub entries.** Articles cited across many tickets in different projects. These are the most valuable knowledge assets and deserve priority in expert verification and maintenance.

**Knowledge gaps.** A dense cluster of tickets that link to each other but have no KB entry near the centre. That pattern signals a topic clients keep asking about that hasn't been written up yet.

**Cluster drift.** A high-similarity bridge entry connecting two otherwise unrelated tag clusters may need richer tagging, splitting into two entries, or promotion to a cross-cutting concept.

**For Customer Zero specifically:** as a consultant building up the KB, a periodic graph review is a meaningful curation tool — roughly the equivalent of reviewing a wiki's "orphaned pages" and "most linked pages" reports, but visual and explorable.

The graph is most useful as an occasional health-check tool during KB curation sessions, not something experts would look at daily.

---

## Marketing value

A living knowledge graph that visibly grows denser as tickets are resolved is a strong visual representation of the product's core value proposition: *expert knowledge that compounds over time*.

This lands well in demos because it makes an abstract idea — "the system gets smarter the more you use it" — concrete and immediate. A visitor watching nodes appear and edges thicken as a demo plays understands the value story faster than any bullet point.

Specific opportunities:
- **Live demo environment**: an anonymised or seeded-data version of the graph embedded in a demo or on the marketing site
- **Customer onboarding**: showing a new customer what their graph will look like after 6 months is a compelling retention argument
- **Case study visuals**: before/after graph snapshots for a customer who has been on the platform long enough to have meaningful data

**One honest limitation:** the graph only looks impressive once there is meaningful data in it. An empty or sparse graph at early onboarding is underwhelming. It is better positioned as a retention and expansion tool — something shown to customers who have been on the platform a while — than as a top-of-funnel sales asset.

---

## Implementation sketch

This does not need to be specced in full detail yet, but the rough shape is:

1. **API endpoint**: `GET /knowledge/graph` returns nodes (KB entries with id, title, tags, usage count) and edges (ticket links + semantic similarity pairs above a configurable threshold)
2. **Rendering**: `react-force-graph` or `Cytoscape.js` — both are well-maintained, handle hundreds of nodes comfortably in a browser
3. **Controls**: filter by tag/industry, toggle edge types (explicit links vs. semantic), adjust similarity threshold slider
4. **Entry point**: a "Graph view" toggle in the `/knowledge` browser (expert and admin only)

Estimated scope: **M** (medium). The data pipeline is already there; this is primarily a UI build.

---

## Recommendation

Add to the roadmap as a post-MVP feature, after the generic knowledge library work is done (since a multi-tenant graph view is more interesting than a single-tenant one). Good candidate to spec in more detail with Ramon given his domain expertise — he will have a strong intuition for which relationship types are most meaningful to surface.