Purpose

The purpose of this initiative is to enable independent releases of Agent Desk from CX Core releases.

Agent Desk is designed as a decoupled Angular-based frontend where all business logic resides in backend services. The UI acts as a presentation layer, consuming:

• API-based interactions (request/response)

• Event-driven interactions (socket-based real-time updates)

Architecture Overview

Agent Desk follows a decoupled, API and event-driven frontend architecture:

• Frontend (Agent Desk - Angular)

  • Responsible for UI rendering and user interaction

  • Contains minimal business logic

  • Consumes backend services via APIs and socket events

• Backend (CX Core / Services)

  • Owns all business logic and workflows

  • Exposes functionality via APIs

  • Publishes real-time updates via socket events

This architecture allows UI enhancements and experience improvements to be released independently, as long as there are no changes to backend contracts or event structures.

This approach enables:

Release Independence Criteria

Agent Desk can be released independently when changes are limited to:

UI-Only Changes (Safe for Independent Release)

• Layout, styling, and UX improvements

• Component-level UI enhancements

• Client-side validations (non-business critical)

• Performance optimizations in UI

• Bug fixes not affecting API/event contracts

UI changes that do not affect backend APIs or event contracts can release independently.

Agent Desk Dependency on CX Core

Though Agent Desk targets independent release, some CX Core changes require synchronized releases.

Agent Desk must release with CX Core in these cases:

In these cases, Agent Desk and CX Core releases must align to ensure compatibility and prevent runtime issues.

Agent Desk Release Semantics

Agent Desk follows Semantic Versioning (SemVer):

Version Format: MAJOR.MINOR.PATCH (e.g., 5.3.1)

Major Releases (N.0.0)

A major release introduces breaking changes that are not backward compatible.

Characteristics:

• Changes requiring updates in dependent systems

• Incompatibility with previous versions

• Mandatory upgrade for continued support

Examples:

• API contract changes (endpoint modification/removal)

• Changes in event (socket/CIM) structures or semantics

• Significant architectural changes

• Removal of deprecated features

Example:
Upgrading from 4.0.0 → 5.0.0 introduces new capabilities but breaks compatibility with older versions.

Minor Releases (N.X.0)

Minor releases add new features or enhancements while maintaining backward compatibility.

Characteristics:

• Non-breaking additions

• Optional upgrades

• Compatible with existing integrations

Examples:

• New UI components or screens

• Additional filters, views, or configurations

• Enhancements to existing features

Patch Releases (N.X.X)

Patch releases focus on stability improvements and fixes.

Characteristics:

• Fully backward compatible

• Non-disruptive

• Safe to upgrade or downgrade

Examples:

• Bug fixes

• UI improvements (layout, styling, usability tweaks)

• Performance optimizations

• Security patches

Example:
A bug in 5.3.0 is fixed in 5.3.1 without impacting existing functionality.

The Tagging Strategy: Independent vs. Coupled

When Releasing Independently

The Agent Desk should have its own version lifecycle. If Core is at 5.1.0, the Agent Desk does not need to stay at 5.1.0. It should start its own sequence (e.g., 2.4.0).

• Small Fixes: Increment the patch (e.g., 2.4.1).

• New Features: Increment the minor (e.g., 2.5.0).

• Breaking UI Changes: Increment the major (e.g., 3.0.0).

When Releasing Necessarily with Core

If a Core change (e.g., a new API endpoint) is required for the Agent Desk to function, we

still use independent version numbers, but tag the release metadata or use a manifest file to lock the dependency.

• Strategy: Agent Desk 2.5.0 specifies that its min_core_version is 5.1.0.

The "Base Release" Strategy

When the Agent Desk releases independently but must work with any Core version within a specific range (e.g., Core 5.x.x), you use Range-Based Versioning.

• Tag: Agent-Desk v2.5.0 (Compatible with Core ^5.1.0)

Graphical Representation of Version Lineage

Independent Release Flow

In this scenario, the Agent Desk iterates rapidly on UI/UX without waiting for Core.

Coupled/Compatible Release Flow

In this scenario, a Core API change forces an Agent Desk update.

• CX release (CX

Automated Tracking (The "Metadata" Method)

To ensure the graphical views stay accurate without manual work, you should track the compatibility in your code metadata:

1. In the Agent Desk Repository: Add a manifest.json file.

   JSON
   

   {
     "version": "2.1.4",
     "compatible_core_range": "^5.2.0"
   }
   

2. The "Handshake" Check: When the Agent Desk starts up, it can call a /version endpoint on the Core server. If the versions aren't compatible according to the logic, the UI can display a warning: "Warning: You are using Agent Desk v2.1 with an unsupported Core version (v4.0)."

Additional Guidelines (Recommended Enhancements)

Backward Compatibility Principles

• Maintain backward compatibility in minor and patch releases

• Clearly document breaking changes in major releases

Release Documentation

Each release should include:

• Release notes

• Impact analysis (breaking vs non-breaking)

• Migration steps (for major releases)

Version Alignment Strategy

• Agent Desk can lead CX Core for UI-only changes

• Must align when API or event contract changes occur

Feature Flagging (Recommended)

• Enable independent rollout of UI features

• Decouple feature availability from backend readiness

• Support gradual rollout and rollback

Rollback Strategy

• Patch and minor releases should support quick rollback

• Major releases should include fallback strategies

Summary

This initiative enables independent, faster, and more flexible Agent Desk releases through a decoupled, API and event-driven architecture.

It defines when alignment with CX Core is required and adopts semantic versioning and structured release practices to ensure both stability and agility in development and deployment.

Scenarios

• CX5.0.3 released (AgentDesk included)

  • Agent Desk (5.1.0) released

  • Agent Desk (5.2.0) released

  • Agent Desk (6.0.0) released

• CX5.2.0 (AgentDesk (6.0.0) included)

• Identify how and where to maintain compatible versions

  • via helm charts?

  • any other possible solutions?