Architecture Roadmap: Headless Core Preparation

[utkuakyuz]

Technical Debt: Prepare for Headless Core Architecture

Context

virtual-react-json-diff has grown beyond a simple UI wrapper and now includes meaningful diff orchestration logic such as:

• comparisonOptions (ignoreKeys, ignorePaths, compareStrategy)
• line / object statistics
• some other performance optimizations

While the current React-based structure works well, this logic is increasingly framework-agnostic and could be reused by other adapters (Vue, Svelte, etc.) in the future.

Problem

At the moment, UI concerns and diff orchestration logic are partially coupled. This makes future framework support and long-term maintainability harder than necessary.

Goal

Prepare the codebase for a future headless core architecture without introducing breaking changes or premature refactors.

Scope (non-breaking, preparation only)

• Clarify architectural boundaries between:

  • Diff engine (json-diff-kit)
  • Diff orchestration (this library’s core value)
  • UI adapter (React)

• Identify logic that can eventually be moved into a framework-agnostic core

• Improve separation of concerns where possible without changing public APIs

Out of scope (for now)

• No monorepo
• No separate core package yet
• No Vue/Svelte adapters
• No major refactor

Next step

Create an internal ARCHITECTURE.md document describing:

• Diff lifecycle
• Current responsibilities
• Future headless core vision

This issue is intentionally forward-looking and serves as a foundation for future technical decisions.