Skip to content

Wikantik

Technical diagram illustrating the modular decomposition of wikantik-main and the CI complexity ratchet

Decomposing the God Module: Package Extraction and the Complexity Ratchet

From Wikantik · 22 articles · latest

Technical diagram illustrating the modular decomposition of wikantik-main and the CI complexity ratchet
Modular decomposition: Decomposing the legacy WikiEngine core into bounded domain packages, governed by an automated CI complexity ratchet.

In monolithic codebases, modular boundaries erode unless they are strictly enforced by automated build tooling.

Following the initial fork from Apache JSPWiki, Wikantik accumulated substantial new functionality directly within its core module, wikantik-main. Early development prioritized delivering core agent features—dense vector indexing, Model Context Protocol endpoints, and relational authorization—leading engineers to place disparate subsystems into the same package.

By mid-2026, wikantik-main housed Markdown rendering, JAAS security filters, hybrid search, entity extraction pipelines, Apache Tika document ingestion, and legacy page storage providers.

The central orchestration class, WikiEngine, exhibited a Coupling Between Objects (CBO) metric of 143, coupling a single class to nearly 150 distinct types across the repository. This high degree of coupling impaired test isolation and increased incremental compile times.

Decomposing this module was necessary to establish maintainable domain boundaries and unblock parallel development.

Domain Extraction Strategy

Rather than attempting a full rewrite, the team decomposed wikantik-main incrementally through a series of discrete sub-modules governed by Architecture Decision Records (ADRs).

Specific functional domains were extracted into dedicated Maven sub-modules with explicit, unidirectional dependency graphs:

  • wikantik-jdbc: Encapsulates relational persistence, HikariCP connection pooling, Flyway database migrations, and PostgreSQL transaction boundaries.
  • wikantik-ontology: Isolates the embedded Apache Jena TDB2 engine, the W3C RDF/OWL ontology T-Box, SHACL validation gates, and the public SPARQL endpoint.
  • wikantik-ingest: Encapsulates Apache Tika 3.3.0 binary parsing, isolating heavy PDF and office document reflow pipelines from the core wiki lifecycle.
  • wikantik-mcp-core: Standardizes protocol schemas, tool annotations, and JSON-RPC dispatching shared across both MCP daemon gateways.
  • wikantik-insights: Manages background analytics, audit log rollups, and content drift metrics.

Under ADR-0008, WikiEngine was refactored to replace direct object instantiation with dependency injection and dedicated lifecycle managers. The class CBO metric dropped from 143 to 86, removing cyclical package references and reducing incremental build duration.

Continuous Enforcement: The CI Complexity Ratchet

Architectural decoupling degrades over time without automated gating. Wikantik added a Complexity Ratchet to continuous integration using static analysis rules. The ratchet tracks class coupling (CBO), cyclomatic complexity, and method lengths. The metric ceiling is monotonic: changes can decrease or preserve complexity, but any pull request that increases coupling or complexity fails the build.

Enforcing Architectural Bounds in Release 2.4.60

The continuous ratchet directly affected delivery during the release of milestone 2.4.60. When new context-bundling and verification features were introduced, several classes exceeded established complexity thresholds, failing the build pipeline.

Rather than relaxing the threshold, the engineering team restructured the offending classes in commit 786aac8335:

  • Decomposing BundleRerankers: Split monolithic bundle reranking logic into discrete strategy implementations.
  • Extracting VerificationStore: Separated verification metadata persistence from general page revision tracking.
  • Refactoring PageRevisions: Decoupled raw disk diffing operations from historical metadata indexing.

Subsequent commit 46f4ea216f introduced the KgBatchLookups interface and the EventActors helper class, standardizing batched data access patterns while satisfying all static analysis gates.

Remaining Architectural Coupling: wikantik-renderer

A transparent accounting of Wikantik's architecture must also document remaining technical debt. As detailed in WikantikCritiqueAndMarketPosition.md, wikantik-main retains legacy coupling that warrants further extraction.

Specifically, the Markdown rendering pipeline has not yet been extracted into a standalone wikantik-renderer module. The Flexmark parsing pipeline remains tightly coupled to historical JSPWiki-era Plugin and PageFilter lifecycles.

These legacy interfaces pass mutable WikiContext instances that bundle HTTP servlet requests, user session handles, and engine references. Decoupling the text rendering engine from this servlet context requires redesigning the plugin contract, which remains an open roadmap item.

Implementation Takeaways

The modular extraction in Wikantik illustrates two practical engineering principles for legacy refactoring:

  1. Partition by Storage and Protocol Domains: Modularize code along operational data boundaries (relational SQL, RDF graphs, flat-file storage, document ingestion) rather than abstract functional tiers.
  2. Automate Structural Invariants: Relying on manual code review to manage coupling fails under deadline pressure. Monotonic static analysis checks in CI convert architectural boundaries into verifiable build requirements.

The next article analyzes storage performance, detailing the October 2026 profiling campaign that uncovered an uncompacted 79 GB disk leak in the Apache Jena TDB2 graph store.

References and Source Code Truth

Keep reading

Comments