In early 2026, as we added graph features to Wikantik, code and agent prompts frequently conflated two different structures: the hyperlinks connecting wiki pages, and the domain entities described inside those pages.
This conflation caused subtle bugs, bloated database schemas, and messy user interfaces. An author linking from DistributedTracing to OpenTelemetry was doing something fundamentally different than an automated pipeline inferring that OpenTelemetry implements DistributedTracing.
To restore architectural clarity, Wikantik established a strict domain boundary: The Page Graph and The Knowledge Graph are distinct, decoupled subsystems with different data models, storage backends, and target audiences.
The Page Graph: Document Topology for Humans
The Page Graph represents the physical network of documentation authored in the wiki. Its primary audience is human researchers, technical authors, and navigational aids.
The architectural rules governing the Page Graph are deliberately minimalist:
- Pure Wikilinks as Edges: An edge in the Page Graph exists if, and only if, an author explicitly typed a wikilink in the markdown body: either a native
[[TargetPage]]or a markdown link[Anchor Text](TargetPage). No synthetic edges, no inferred links. - Stable Identity via Canonical ULIDs: Traditional wikis break inbound links and search references whenever an article is renamed or moved. Wikantik introduced a
canonical_idin page frontmatter: a 26-character Universally Unique Lexicographically Sortable Identifier (ULID) assigned on page creation (e.g.,01KTGSV428AK6A68N69X235ZHT). Even if an article's title changes from "Kubernetes Ingress" to "Envoy Gateway Ingress", all references and version history remain anchored to the immutable canonical ID. - Cluster Declarations: Rather than forcing hierarchical folder trees onto document storage, Wikantik organizes pages through flat cluster hubs. A cluster exists if, and only if, exactly one page carries
type: hubwith a declaredcluster:tag. Member articles declare their primary and secondary cluster memberships in frontmatter, enabling dynamic navigation while keeping underlying file storage flat and portable. - Implementation: Managed by
com.wikantik.pagegraph.*, backed by Lucene reference indexes and rendered interactively at/page-graphusing Cytoscape.js.
In early iterations, Wikantik experimented with a hybrid relations: YAML block in page frontmatter, allowing authors to declare typed edges between pages (e.g., relations: [isA: ArchitecturePattern]). In practice, out of nearly 1,000 production pages, only 3 ever used it. It created an awkward halfway house between document linking and formal ontologies. On May 2, 2026, the feature was completely retired. The Page Graph became strictly the graph of written wikilinks.
The Knowledge Graph: Semantic Triples for Machines
If the Page Graph is a map of documents, the Knowledge Graph is a map of the real-world concepts, entities, and relationships discussed inside those documents. Its primary consumers are AI agents, semantic query engines, and automated auditors.
The architecture of the Knowledge Graph operates at a higher level of formal abstraction:
- Entity-Relationship Triples: Nodes represent extracted domain entities (Concepts, Software Libraries, Protocols, Organizations). Edges represent typed semantic predicates (
implements,deprecates,dependsOn,authoredBy). - Storage and Relational Schema: Persisted in dedicated PostgreSQL tables (
kg_entities,kg_relations,kg_entity_mentions) with full provenance metadata linking every relationship back to the source document span that asserted it. - The RDF/OWL Ontology: In June 2026, Wikantik introduced the
wikantik-ontologymodule. This formalized a queryable W3C standard T-Box encompassing 9 entity classes, 5 content classes, and 21 formal predicates. - W3C Standards Compliance:
- SHACL Write-Time Gate: Validates semantic consistency and constraints before relationships are committed.
- SPARQL 1.1 Endpoint: Exposed at
/sparqlfor federated semantic queries. - Dereferenceable Linked Data IRIs: Concepts resolve via HTTP URI dereferencing at
/id/{type}/{id}, emitting standard JSON-LD and Turtle representations.
Contrasting the Two Graph Subsystems
Separating the two graph models simplified both the codebase and the API surface. The differences are summarized below:
| Architectural Dimension | The Page Graph | The Knowledge Graph |
|---|---|---|
| Node Entity | A Markdown Document / Page | An Extracted Concept or Entity |
| Edge Definition | A real wikilink written by an author | A typed predicate (e.g., dependsOn) |
| Curator & Source | Human writers and editors | Extraction pipelines and admin curators |
| Primary Purpose | Navigation, orphan/broken link triage | SPARQL queries, entity traversal for AI |
| Query Endpoints | /page-graph, REST /api/pages/* | /sparql, /knowledge-mcp, /id/* |
A Derived Dimension: Version-Pinned Citations
Sitting between the two graphs is a third, specialized relationship: the Citation Graph. When an article cites another document, an author inserts an inline cite:// tag.
At save time, Wikantik resolves the citation, records it in the citations database, and pins it both to the exact version number and a cryptographic content hash of the cited text span. When the upstream document is subsequently edited, Wikantik flags the citation as stale or drifted, allowing automated audit tools to notify editors when facts need re-verification.
With document links and semantic triples separated, the next step was exposing these capabilities to AI agents through dedicated Model Context Protocol (MCP) servers.
Comments