Page Graph vs. Knowledge Graph (and Citation & Ontology Layers)

Product Overview: See Page Graph on wikantik.com for the interactive visual walkthrough.

Wikantik maintains three distinct graph structures over a single Markdown corpus—plus a materialized RDF/OWL Ontology projection. Confusing the Page Graph with the Knowledge Graph is the single most common source of architectural bugs, wrong MCP tool selection, and broken queries. In Wikantik code, identifiers never use the bare word graph: they always specify pageGraph (page_links) or knowledgeGraph (kg_*).

1. Visual Architecture: How the Three Graphs & Ontology Fit Together

Every Markdown page saved through PageManager simultaneously participates in the Page Graph (structural navigation & wikilinks), the Citation Graph (section-pinned provenance), and—when kg_include: true—feeds the Knowledge Graph (LLM-extracted domain entities and typed predicates), which in turn projects into the Apache Jena TDB2 RDF/OWL Ontology.

flowchart TB
    subgraph Source["Single Source of Truth (Markdown + YAML Frontmatter)"]
        MD["Wiki Page (Slug + canonical_id ULID)<br/>Frontmatter: type, cluster, related, cites<br/>Body: [[Wikilinks]], cite:// spans, technical prose"]
    end

    subgraph PG["1. Page Graph (Deterministic Editorial Topology)"]
        PL[("page_links & page_canonical_ids<br/>Real [[HybridRetrieval]] & [text](HybridRetrieval) links<br/>+ Hub/Cluster Structural Spine")]
        PGUI["Surfaces:<br/>/page-graph (Cytoscape UI)<br/>get_backlinks, get_outbound_links,<br/>list_clusters, get_briefing"]
        PL --> PGUI
    end

    subgraph CG["2. Citation Graph (Self-Healing Section Provenance)"]
        CIT[("citations Table<br/>cite://TargetPage#Heading<br/>Pinned Version + Span SHA-256 Hash")]
        CITUI["Surfaces:<br/>/admin/drift/citations<br/>list_stale_citations (MCP)"]
        CIT --> CITUI
    end

    subgraph KG["3. Knowledge Graph (Semantic Domain Entities & Predicates)"]
        KGT[("PostgreSQL kg_* Tables<br/>kg_nodes (9 classes) · kg_edges (21 predicates)<br/>kg_proposals · Mention-Centroid Vectors")]
        KGUI["Surfaces:<br/>/admin/knowledge-graph<br/>query_nodes, traverse, find_similar,<br/>search_knowledge, propose_knowledge"]
        KGT --> KGUI
    end

    subgraph ONT["4. Materialized RDF/OWL Ontology (Formal Linked Data)"]
        TDB2[("Apache Jena TDB2 Store<br/>wikantik.ttl T-Box + SHACL Gate<br/>Public ACL-Filtered A-Box")]
        ONTUI["Surfaces:<br/>/sparql · /id/* · /export/*<br/>sparql_query, get_ontology (MCP)<br/>Page SSR JSON-LD @type"]
        TDB2 --> ONTUI
    end

    MD -- "Save-Time AST Link Scanner" --> PL
    MD -- "Save-Time Citation Filter" --> CIT
    MD -- "Async LLM Extractor + Human/Judge Review" --> KGT
    PL -- "Page & Concept Projectors" --> TDB2
    KGT -- "Entity & Edge Projectors (SHACL-Gated)" --> TDB2

2. Side-by-Side Comparison Matrix

3. Deep Dive: Why Page Graph and Knowledge Graph Must Never Be Conflated

3.1 The Page Graph: Editorial Navigation & Structural Spine

The Page Graph answers "How are documents organized and linked by authors?"

• Edges are strictly real wikilinks parsed from Markdown bodies ([text](HybridRetrieval) and [[HybridRetrieval|Alias]]).
• Companion Structural Spine: Alongside wikilink edges, StructuralSpinePageFilter maintains page_canonical_ids (26-character ULIDs that survive page renames via page_slug_history) and Cluster Declarations (Cluster Declaration Design), where a hub page (type: hub, cluster: "distributed-systems") declares the cluster and member articles join it via scalar or list-valued cluster: frontmatter.
• UI & API: Visualized in the interactive Cytoscape graph at /page-graph (colored by cluster and node degree, with orphan and broken-link overlays) and queried via /api/page-graph and /admin/page-graph/*.

3.2 The Knowledge Graph: Domain Entities, Predicates & Mention-Centroid Embeddings

The Knowledge Graph answers "What real-world concepts, technologies, and protocols exist inside the prose, and how do they relate?"

• A single article like Large Language Models Since 2020 is one node in the Page Graph, but it yields dozens of nodes in the Knowledge Graph (DeepSeek-R1, Group Relative Policy Optimization, Multi-Head Latent Attention, Chinchilla Scaling Laws) connected by typed predicates (DeepSeek-R1 --uses--> Group Relative Policy Optimization).
• Mention-Centroid Entity Embeddings: Every KG entity node v \in V_{\text{KG}} is embedded into the same vector space as document chunks by averaging the dense vectors \vec{u}_c of all section chunks M(v) that mention v:

This enables the find_similar MCP tool to discover conceptually analogous entities across completely different clusters (even when no direct wikilink or KG edge connects them yet).

4. Practical Decision Guide: Which Tool Should an Agent Call?

// 1. Page Graph: "Which pages link to HybridRetrieval?"
{"name": "get_backlinks", "arguments": {"pageName": "HybridRetrieval"}}

// 2. Knowledge Graph Traversal: "What technologies depend on or use pgvector?"
{"name": "traverse", "arguments": {"startNode": "pgvector", "direction": "BOTH", "maxDepth": 2}}

// 3. Cross-Graph SPARQL Query: "Find all articles in cluster 'distributed-systems' and their SKOS broader hierarchy"
{
  "name": "sparql_query",
  "arguments": {
    "query": "PREFIX wikantik: <https://wiki.wikantik.com/ontology#> PREFIX dct: <http://purl.org/dc/terms/> SELECT ?page ?title WHERE { ?page a wikantik:Article ; dct:title ?title ; dct:subject <https://wiki.wikantik.com/id/concept/distributed-systems> . } LIMIT 20"
  }
}

5. Historical Cleanup: What Was Retired in 2026 (Do Not Resurrect)

To eliminate dual-maintenance bugs and schema drift, three legacy mechanisms were permanently removed between April and August 2026:

1. GraphProjector (Retired 2026-04-24): Previously, a PageFilter projected custom YAML frontmatter keys (depends-on:, enables:, part-of:, uses:) directly into kg_nodes and kg_edges. This polluted the entity graph with page slugs and bypassed the closed 21-predicate vocabulary. See Graph Projector (Retired).
2. Typed Page relations: Frontmatter (Removed 2026-05-02): An early design in Structural Spine Design proposed a relations: block in YAML frontmatter for typed page-to-page links, alongside a page_relations table and traverse_relations MCP tool. Only 3 of 951 pages ever used it; it was dropped in favor of standard wikilinks + cites: contract citations (SA-13).
3. The hubs: Frontmatter Field & HubSyncFilter (Retired 2026-08-15): Consolidated into cluster: by Cluster Declaration Design (`ADR-0009`). Never generate hubs:, relations:, or depends-on: in frontmatter; use cluster:, related:, and cites:.

Cluster Hub: Wikantik Platform Development Hub: Architecture, MCP Protocols, and Agent Briefings (wikantik-development)