Skip to content

Wikantik

Technical architectural blueprint of Wikantik post-fork showing the tri-tier storage engine, dual MCP gateways, and React interface

Beyond the Fork: Settling the Architecture of an Agent-Grade Knowledge Base

From Wikantik · 22 articles · latest

Technical architectural blueprint of Wikantik post-fork showing the tri-tier storage engine, dual MCP gateways, and React interface
The post-fork system topology: Decoupled flat-file storage, relational pgvector indexing, and semantic RDF graphs supporting both human developers and autonomous AI agents.

In April 2026, Wikantik completed its initial fork from Apache JSPWiki. The initial release resolved the runtime and framework migration: the servlet container was ported to Jakarta EE 10 (Servlet 6.0), the legacy JSP presentation layer was replaced with a Vite and React single-page application (SPA), and an initial Model Context Protocol (MCP) bridge was deployed.

With runtime portability established, the primary design challenge centered on data architecture: defining the storage and protocol contracts for a knowledge platform serving two distinct access patterns simultaneously.

Human developers require responsive page rendering, flexible Markdown syntax, intuitive visual navigation, and loose document structures. Autonomous AI agents require deterministic JSON payloads, verifiable version-pinned provenance, strict token budgeting, and zero hallucinated synthesis.

Balancing these requirements required defining a multi-tier storage model and partitioning the protocol boundaries between human and automated consumers.

The Tri-Tier Storage Model

Rather than consolidating all data into a single document store or relational database, the architecture divides data persistence into three specialized, decoupled storage tiers based on operational requirements:

1. Durability and Source of Truth: The Flat Filesystem

Human-authored wiki pages remain stored as raw CommonMark files on local non-volatile storage, managed by VersioningFileProvider.

Preserving page bodies as standard text files ensures that the underlying corpus remains accessible without proprietary database tooling. System administrators and automated scripts can inspect, grep, backup, or synchronize pages directly using standard POSIX utilities or Git repositories.

2. Relational Metadata and Dense Vectors: PostgreSQL with pgvector

While flat files provide durable storage, they do not efficiently support real-time permission evaluation, section chunking, or similarity searches. Wikantik uses PostgreSQL 18 with the pgvector extension for relational and vector workloads:

  • Relational Access Control: The policy_grants table manages dynamic permission inheritance, replacing legacy flat XML files.
  • Structural Chunking: The kg_content_chunks table stores articles segmented into discrete sections indexed by heading paths.
  • Dense Vector Embeddings: Chunk embeddings are stored in content_chunk_embeddings, using Hierarchical Navigable Small World (HNSW) indexing with cosine distance metrics.

3. Semantic Ontology and Triples: Apache Jena TDB2

Vector embeddings capture semantic similarity but cannot represent explicit domain ontologies or relational constraints. To support deterministic graph queries, Wikantik embeds an Apache Jena TDB2 triple store holding a formalized W3C RDF/OWL ontology.

The ontology defines 9 entity classes, 5 content classes, and 21 typed predicates. It is accessible via a SPARQL 1.1 endpoint (/sparql) and dereferenceable IRIs (/id/{type}/{id}).

Design Trade-Off: Coordination Across Storage Tiers

Operating three distinct storage engines—POSIX files, PostgreSQL transactions, and Jena TDB2 B+trees—without a distributed two-phase commit protocol introduces consistency boundaries. If a database insert fails after a page write commits to disk, the derived vector index becomes stale until reconciliation runs. Managing these consistency seams required building explicit synchronization and repair jobs.

Protocol Separation: REST and Model Context Protocol

To prevent coupling between human UI requirements and agent workflows, Wikantik routes incoming traffic through two separate protocol gateways:

  • Presentation Tier (React SPA + REST): Serves interactive web traffic, providing sub-second page rendering, Cytoscape graph visualization, Markdown editing previews, and cluster navigation.
  • Agent Tier (Dual MCP Servers): Standard Model Context Protocol endpoints partition automated agent interactions into read-only grounded retrieval (/knowledge-mcp) and authenticated management operations (/wikantik-admin-mcp).

Technical Debt Identified in the Initial Post-Fork State

While the functional baseline operated as intended, rapid prototyping during the initial post-fork phase left concrete technical debt across several subsystems:

  1. Monolithic Core (wikantik-main): To minimize build complexity early on, Markdown rendering, hybrid search, entity extraction, JAAS authentication, and legacy page providers were consolidated within wikantik-main. The central coordinator class, WikiEngine, exhibited a Coupling Between Objects (CBO) metric of 143.
  2. In-Memory Cache Incoherence: Page listings and metadata were cached using simple time-to-live (TTL) policies. Asymmetrical cache expirations between collection lists and individual item entries occasionally resulted in deleted or renamed pages appearing in directory views.
  3. Synchronous Write Overhead: Page save requests executed synchronous Lucene reindexing, frontmatter parsing, and Jena TDB2 transaction commits directly on the HTTP request thread, driving save latencies above 250 milliseconds under concurrent writes.

Stabilization Objectives for Milestone 2.4

Reaching production stability in milestone 2.4 required addressing these structural constraints directly:

  • Decomposing wikantik-main into modular Maven packages governed by CI architecture gates.
  • Instrumenting low-level Linux syscall and database statement profiling to resolve disk bloat and query amplification.
  • Hardening filesystem write paths with explicit POSIX atomic durability semantics.

The subsequent articles in this series detail the specific defects encountered, the root causes identified through profiling, and the architectural changes implemented to resolve them.

References and Source Code Truth

Keep reading

Comments