ADR-001: Extract Manager Interfaces to API

• Status: Approved
• Date: 2026-03-23
• Author: jakefear

Context

The Wikantik platform was originally a fork of Apache JSPWiki. In the legacy architecture, all core logic (page management, reference tracking, group management, etc.) was contained within the monolithic wikantik-main module.

When the Model Context Protocol (MCP) servers were introduced, they needed to interact with these core managers. However, depending directly on wikantik-main was problematic:

1. Circular Dependencies: Modules like wikantik-rest and the MCP servers would end up in complex dependency loops.
2. Testing Overhead: Testing an MCP tool required bootstrapping the entire WikiEngine, which was slow and fragile.
3. Tight Coupling: It was impossible to use the MCP tools in a lightweight environment or with in-memory stubs.

Decision

We decided to extract the core "contracts" of the wiki engine into a lightweight, logic-free module: wikantik-api.

The following interfaces were moved from wikantik-main to wikantik-api:

• PageManager
• ReferenceManager
• GroupManager
• UserManager
• WikiEngine (the interface)
• GroupDatabase
• UserDatabase
• AttachmentManager

Additionally, core data models (WikiPage, WikiContext) and exceptions (VersionConflictException) were also moved to the API module.

Consequences

Positive

• Decoupling: Modules can now depend only on the interfaces in wikantik-api, significantly reducing the dependency graph complexity.
• Fast Testing: Enabled the Test Stub Conversion, allowing for high-speed, isolated unit tests using in-memory stubs like StubPageManager.
• Hexagonal Alignment: This move was the first major step toward a clean Hexagonal Architecture.
• Portability: The API module is lightweight and can be included in external tools or clients without pulling in the entire engine.

Negative

• Initial Refactoring Effort: Required updating hundreds of imports across the codebase.
• Complexity of Wiring: Increased the importance of a robust Dependency Injection (DI) system to wire implementations to these new interfaces.

See Also

• Wikantik Development — The modernization timeline.
• Hexagonal Architecture — The long-term architectural goal.
• Test Stub Conversion — The immediate benefit of this ADR.