Skip to content

Wikantik

Comprehensive enterprise system architecture blueprint of modern Wikantik showing RAG-as-a-Service, context bundle assembly, and agent integration

RAG-as-a-Service and the Modern State: Context Bundling, Derived Pages, and Grounded Truth

From Wikantik · 22 articles · latest

Comprehensive enterprise system architecture blueprint of modern Wikantik showing RAG-as-a-Service, context bundle assembly, and agent integration
The modern Wikantik architecture: An end-to-end RAG-as-a-Service platform combining Apache Tika document ingestion, heading-aware chunking, hybrid retrieval, and zero-synthesis context bundling.

Modernizing a twenty-year-old codebase does not require a clean-slate rewrite. Across 2026, Wikantik evolved incrementally from Apache JSPWiki 2.12.3 to milestone 2.4.60 by replacing individual subsystems one layer at a time while keeping the underlying file storage intact.

Over nine months, the servlet container was updated to Jakarta EE 10, the JSP UI was replaced with a React SPA, security policies moved to PostgreSQL RBAC, and hybrid BM25 + pgvector search was added.

Alongside these infrastructure updates, the platform's role expanded from a human-browsed wiki into a RAG-as-a-Service context engine that serves version-pinned source excerpts to AI agents.

The Architecture of Context Bundling: Zero Answer Synthesis

Most commercial "AI search" tools attempt to synthesize answers directly: they ingest documents, run a query, and prompt a large model to generate conversational paragraphs. In enterprise engineering, this synthesis step is frequently a liability. It introduces hallucination risks, strips away author attribution, and obscures whether an answer came from production documentation or an LLM's training priors.

Wikantik rejected answer synthesis at the platform layer. Instead, Wikantik operates as a pure, high-performance context provider via its Context Bundle engine (exposed via GET /api/bundle?q= and the assemble_bundle MCP tool).

When an agent or pipeline requests context, the bundle assembly pipeline executes six discrete stages:

  1. Hybrid Shortlisting: Queries both Lucene BM25 and PostgreSQL pgvector, executing Reciprocal Rank Fusion to identify the top candidate sections.
  2. Deduplication: Normalizes overlapping sections using collision-proof content hashes, ensuring an agent's context window is never wasted on redundant excerpts.
  3. Token-Budgeted Selection: Emits sections strictly up to the caller's specified token envelope (e.g., 4,000 tokens), selecting the highest-utility chunks.
  4. Cryptographic Version Pinning: Every included section is stamped with an immutable citation tuple: the document's canonical_id, exact version integer, and a SHA-256 hash of the cited text span.
  5. Structured Delivery: Emits a clean JSON or Markdown bundle containing verbatim source text, precise heading breadcrumbs, and provenance metadata.

The calling agent receives verbatim source text together with deterministic version and hash metadata for citation verification.

Architectural Insight: The Power of Ingesting Derived Pages

Enterprise technical knowledge does not live solely in markdown files; it is scattered across architectural PDFs, design slide decks, and Word specifications. Wikantik integrated Apache Tika 3.3.0 via POST /api/ingest. When a binary attachment is uploaded, Tika parses the document hierarchy and machine-reflows it into a "derived" wiki page. The derived page enters the standard chunking, embedding, and hybrid search pipeline, allowing agents to query legacy documentation seamlessly.

What Was Replaced vs. What Was Kept

Looking across the entire evolutionary arc reveals why progressive refactoring succeeded where clean-slate rewrites so often fail.

What Was Replaced

  • The Presentation Monolith: 20-year-old server-side JSP scriptlets and custom tag libraries were replaced by a modern Vite + React SPA.
  • Static XML Security: Flat jspwiki.policy files were replaced with relational RBAC tables and Pac4j enterprise SSO (OIDC/SAML).
  • Brittle Legacy Syntaxes: Old custom wiki markup was completely retired in favor of native CommonMark/Flexmark rendering.
  • The GraphRAG Dead End: 2,464 lines of complex, page-level Knowledge Graph reranking code were purged after empirical benchmarks showed zero recall lift.
  • Monolithic Tools: Replaced with specialized Dual-MCP gateways (/knowledge-mcp and /wikantik-admin-mcp).

What Survived as Load-Bearing Foundations

  • The PageProvider Abstraction: The core abstraction for managing physical page storage on disk—and its VersioningFileProvider implementation—remains fundamentally sound. Page histories, incremental diffs, and file locking continue to operate directly on disk.
  • Apache Lucene BM25 Core: Lucene remains the lexical backbone of our hybrid retrieval engine, providing fail-closed reliability whenever neural embedding endpoints experience latency.
  • Plugin & Filter Architecture: The classic filter pipeline (pre-save, post-save, rendering filters) was modernized rather than discarded, serving as the exact lifecycle hooks that power chunk projection and citation resolution today.

The Modern System in Practice

Today, Wikantik supports both interactive users and automated agent workflows:

  • Human developers read, write, and explore concepts using a responsive React SPA and visual page graphs.
  • AI coding assistants query /knowledge-mcp to pull verified context bundles directly into their reasoning context.
  • Autonomous curation agents run through /wikantik-admin-mcp to detect citation drift, repair broken links, and keep technical documentation synchronized with git repositories.
  • Semantic query engines query the public W3C SPARQL endpoint to inspect entity relationships governed by formal SHACL gates.

Architectural Takeaways

The journey from Apache JSPWiki 2.12.3 to Wikantik 2.4.60 yields three enduring architectural lessons for technologists building systems in the AI era:

  1. Respect the Foundation: Battle-tested storage engines and inverted index algorithms (like Lucene) possess decades of edge-case hardening that new vector-only tools have yet to match. Build hybrids, not replacements.
  2. Measure Relentlessly: Industry buzzwords (like GraphRAG) must be subjected to rigorous empirical evaluation. When a feature adds latency and complexity without moving the recall metric, have the courage to delete it.
  3. Design for Dual Citizens: The future of software documentation belongs neither to humans alone nor to machines alone. Systems must be engineered from the ground up with clean presentation layers for human intuition, and robust, token-efficient protocols for autonomous intelligence.

References and Source Truth

Keep reading

Comments