ADR-024: Command Center Architecture

Context

OneCMS requires a global command center to enable fast navigation, action execution, and discovery across modules and deep-linked sections.

Initial implementation introduced fuzzy search (Fuse.js), route-based indexing, and a command palette UI. As the system evolved, multiple concerns emerged:

• heterogeneous data sources (routes, settings, content, actions)
• need for consistent search behavior across domains
• separation between discovery (search) and execution (actions/navigation)
• requirement for extensibility without coupling UI, data, and execution logic

A clear architectural model was required to prevent tight coupling and ensure scalability.

Decision

The Command Center is implemented as a layered, adapter-driven system with strict separation of concerns.

1. All searchable data is normalized into a unified IndexItem structure. This is the only data shape consumed by the search system.
2. Each domain (routes, settings, content, actions) must provide a normaliser adapter that converts raw domain data into IndexItem[]. Adapters are pure and do not contain execution or UI logic.
3. Index composition is handled via a registry-based system where all adapters are registered and invoked to produce a unified index.
4. Fuzzy search (Fuse.js) is used strictly as a scoring mechanism over the unified index and does not contain domain-specific logic.
5. Search results are transformed into a UI-facing CommandResult structure via a dedicated adapter layer, isolating library-specific output from the rest of the system.

6. Execution is decoupled from search:
   • navigation is driven by route
   • actions are driven by commandId
     Execution logic is handled by a command registry and executor layer.

7. The UI layer acts as a pure consumer of CommandResult[] and delegates all execution to the executor. It does not perform search, transformation, or business logic.

Consequences

• Enables consistent search and command behavior across all domains
• Allows new data sources to be added via adapters without modifying core logic
• Decouples search, data normalization, and execution for maintainability
• Makes Fuse.js replaceable without affecting UI or adapters
• Introduces additional layers (adapters, registry, executor) that require discipline
• Requires all domains to conform to the IndexItem contract
• Shifts responsibility for search quality to adapter implementations

:::info Value Added

• Adds a unified, fast interaction layer that lets users navigate, find, and act across the entire platform instantly from a single entry point.
• Reduces friction and cognitive load by eliminating the need to remember locations or traverse nested UI structures.
  :::

Notes

• IndexItem is the canonical language of the command system
• Adapters are first-class architectural components, not utilities
• Deep navigation (e.g., nested settings) is handled via enriched indexing, not separate types