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](TestStubConversion)**, 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](HexagonalArchitecture)**.

- **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.