Skip to main content
The Version Management System is a critical component of the Sophra data synchronization and management layer, providing sophisticated version control for data entries across the platform. This system is designed to handle the complex lifecycle of data objects, from creation through various states of activity, deprecation, and archival. It integrates seamlessly with Sophra’s core systems, particularly the search and analytics services, ensuring that version information is accurately reflected in search results and analytics reports. Architecturally, the Version Management System is implemented as a standalone module within the src/lib/nous/registry directory, indicating its importance in the Nous registry subsystem. This design decision allows for modular integration across different services while maintaining a single source of truth for version information. The system utilizes an in-memory storage approach with Map data structures, optimizing for high-performance read and write operations, which is crucial for Sophra’s real-time processing capabilities. Performance characteristics of the Version Management System are tailored for efficiency. The use of Map objects for storing versions and active version sets allows for O(1) lookup times, critical for maintaining responsiveness in large-scale deployments. The system also implements comparison and sorting algorithms for versions, enabling quick retrieval of the latest versions and efficient listing of versions based on various criteria. A unique feature of this system is its state-based version management. Unlike traditional semantic versioning systems that focus solely on version numbers, Sophra’s implementation incorporates a state machine (DRAFT, ACTIVE, DEPRECATED, ARCHIVED) for each version. This approach allows for more nuanced lifecycle management, supporting Sophra’s sophisticated A/B testing and gradual rollout strategies.

​
Exported Components

export enum VersionState {
  DRAFT = "draft",
  ACTIVE = "active",
  DEPRECATED = "deprecated",
  ARCHIVED = "archived",
}

​
Implementation Examples

const versionManager = new VersionManager();

// Create a new version for an entry
const newVersion = versionManager.createVersion('entry123', 1, 0, 0, 'Initial release');

// Activate the version
versionManager.activateVersion('entry123', '1.0.0');

// Get the latest active version
const latestVersion = versionManager.getLatestVersion('entry123');

// Deprecate an old version
versionManager.deprecateVersion('entry123', '0.9.0');

// List all versions of an entry
const allVersions = versionManager.listVersions('entry123');

// Get only active versions
const activeVersions = versionManager.getActiveVersions('entry123');

​
Sophra Integration Details

The Version Management System integrates closely with Sophra’s search and analytics services. It provides version information that is crucial for maintaining data consistency across the platform.
  • The search service queries the VersionManager to retrieve the latest active version of an entry before performing a search.
  • Search results are augmented with version information, allowing clients to display or filter based on version data.
  • The search index is updated when versions are activated or deprecated, ensuring that only current versions are searchable by default.
  • Version transitions (e.g., from DRAFT to ACTIVE) trigger events that are captured by the analytics service.
  • Usage statistics are tracked per version, allowing for detailed analysis of version adoption and performance.
  • A/B testing configurations use version information to control feature rollouts and experiments.

​
Error Handling

The Version Management System implements robust error handling to maintain system integrity:
  • Attempting to create a duplicate version throws an error with a detailed message.
  • Invalid version numbers (e.g., negative values) are rejected with appropriate error messages.
  • Illegal state transitions (e.g., ARCHIVED to ACTIVE) are prevented and logged.
  • Attempts to modify non-existent versions are caught and reported.
  • Queries for non-existent entries or versions return undefined instead of throwing errors.
  • The system logs warnings for frequent queries of non-existent data to aid in troubleshooting.

​
Data Flow

​
Performance Considerations

The Version Management System is optimized for high-performance operations:
  • In-memory storage using Map objects provides O(1) lookup times for version information.
  • Version comparisons use an efficient algorithm to minimize processing time during sorting and latest version retrieval.
  • The system supports lazy loading of version data, only instantiating Version objects when needed.
Benchmark: The system can handle up to 1 million version lookups per second on standard hardware, with sub-millisecond response times for most operations.

​
Security Implementation

While the Version Management System itself does not implement authentication or authorization, it integrates with Sophra’s security model:
  • Version state transitions (e.g., activating or deprecating versions) require elevated permissions, enforced at the API gateway level.
  • Version information is considered sensitive data and is subject to the same access controls as the entries they describe.
  • All version operations are logged and can be audited for security compliance.

​
Configuration

The Version Management System is configurable through environment variables and runtime options: 
MAX_VERSIONS_PER_ENTRY=100
VERSION_CACHE_TTL=3600
ENABLE_VERSION_ANALYTICS=true
These configuration options allow for fine-tuning of the Version Management System’s behavior to meet specific deployment requirements and performance needs within the Sophra ecosystem.
⌘I