Skip to content

Component Versioning

Overview

ARD uses an immutable component system to ensure data integrity, enable seamless collaboration, and maintain complete version history. This approach means you'll never lose data and teammates can work simultaneously without conflicts.

Component Immutability

Core Principle

Every component in the system is immutable. Once created, a component's core parameters cannot be modified — any change creates a new version with the changes applied. However, metadata fields like Notes, Tags, and Hidden/Archived status can be updated directly on the existing version without creating a new one.

Why Immutability?

  • Data Preservation: You never lose previous configurations. Every version is permanently stored.
  • Conflict-Free Collaboration: Multiple users can work on the same component simultaneously without overwriting each other's work.
  • Simulation Reproducibility: If you need to reference a vehicle from a previous simulation, it will always be available exactly as it was.

Cascading Updates

When you edit a component, the immutability principle cascades upward through the component hierarchy:

graph TD
    A[Edit Chassis] --> B[New Chassis Created]
    B --> C[New Vehicle Created]
    C --> D[Vehicle References New Chassis]

    %% Dark-mode friendly styles
    style A fill:#2f5d8a,stroke:#9fbce0,color:#e6eef7
    style B fill:#1f6f5b,stroke:#7fd1bd,color:#e8f6f2
    style C fill:#1f6f5b,stroke:#7fd1bd,color:#e8f6f2

Example: If you edit a chassis component: 1. A new chassis component is created with your changes 2. A new vehicle component is automatically created 3. The new vehicle references the new chassis 4. The original chassis and vehicle remain unchanged in the system

This automatic "bubble up" behavior occurs when you click Save.

Version History Access

Every component includes a version history dropdown showing all previous versions.

Components are identified by their version number, which is displayed next to each version in the history. If you know you want to return to a specific configuration, remember its version number and name.

Version History

Locking a Component

Once a setup is signed off, you can lock it so nobody saves over it by accident.

Locking is available from the setup selector — the lock button on each row, or Lock in the row's actions menu. A locked row shows a lock icon on its version badge, and hovering the badge spells the state out.

To lock several setups at once, select the rows (ctrl/cmd-click, or shift-click for a range) and use Lock in the selection bar. The button reads Unlock when every selected row is already locked, so a mixed selection always resolves to "all locked" in one click.

While a component is locked:

  • Save is blocked. Saving creates the next version in that component's lineage, which is exactly what locking prevents. The Save button is disabled and the API rejects the request.
  • Duplicate is blocked, for the same reason — it also extends the lineage. The Duplicate action is greyed out for locked rows.
  • Editing a child is blocked if a locked component sits above it. Because edits cascade upwards, changing a spring under a locked vehicle would have to create a new vehicle version.
  • Save As is still allowed. It starts a separate lineage under a new name and leaves the locked component untouched. The new component starts unlocked. The one exception is Save As on a child of a locked component: the cascade still has to create a new version of the locked parent, so unlock the parent first.

To make a change, unlock the component first — that extra step is the point: it makes overwriting a signed-off setup a deliberate act rather than an accident.

Locking applies to a row, not to a name — but locking the current version of a name freezes that whole lineage. Saving always stacks the next version on top of the current one, so with v4 of "Baseline Aero" locked, nothing can be saved under that name until it is unlocked, even if you loaded the older v3 from the version history. Locking an older version only blocks saving from that row. Lock state is never inherited by new versions.

Collaborative Workflows

Scenario: Two Teammates Editing Simultaneously

If two teammates wish to edit the same vehicle at once, this is totally okay.

Key Points: - Each teammate creates their own version of the vehicle - No conflicts or overwriting occurs

Initial Component State

When you load a vehicle from a template: - All components start as v1 - They appear immediately in the setup selector - Any edits will create new versions

Best Practices

Organization

  • Use descriptive names when creating new namespaces
  • Remember significant version numbers if you frequently reference specific versions

Team Coordination

  • Communicate version numbers when you are updating a component
  • Use new namespaces when exploring different directions to avoid conflicts

Version Management

  • Don't worry about clutter - the system handles all versions efficiently
  • Use version history to compare changes and understand evolution

Common Workflows

Creating a Track-Specific Variant

  1. Load your base vehicle configuration
  2. Create a new name space for the variant
  3. Edit components for track requirements
  4. Both variants now available in setup selector

Recovering a Previous Configuration

  1. Open the component in setup selector
  2. Click the version history dropdown
  3. Find the version by ID or position in history
  4. Load that version

Next Steps