Upgrade Path Process

The Upgrade Path Process describes how Projects adopt new versions of Business Systems safely and intentionally. Because IMSF uses pinned versions for every Project, upgrades never occur automatically. Instead, they follow a structured, transparent workflow designed to minimise risk while maximising the benefits of system improvements.

This page explains how the upgrade cycle works from receiving an update notification to deploying the upgraded platform.

Why Upgrades Matter

Over time, Business Systems receive improvements: new features, performance enhancements, bug fixes, and structural refinements. The upgrade process ensures Projects can access these benefits without compromising stability.

Upgrades allow Projects to:

• stay aligned with the latest system capabilities
• benefit from new integrations, UI updates, and optimisations
• maintain long-term compatibility with evolving workflows
• avoid technical debt associated with outdated versions

How Projects Are Notified of New Versions

Whenever the Systems Library publishes a new version of a Business System (patch, minor, or major), any Project that uses that system receives a notification inside the Innopo Platform.

The notification includes:

• the new available version
• current version pinned to the Project
• change type (patch, minor, or major)
• a summary of what has changed
• whether migration steps are required

This allows maintainers to evaluate upgrades before making any changes to the Project.

Upgrade Path Overview

The upgrade process consists of several controlled stages. Each stage ensures the Project remains stable and that changes are fully validated before going live.

1. Review update details
2. Create an upgrade branch/environment
3. Apply system updates
4. Merge schema changes and run migrations
5. Validate functionality in staging
6. Perform workflow layer checks
7. Approve and deploy to production
8. Update the Project’s version map

Step 1 — Review Update Details

Maintainers begin by reviewing the system's changelog and migration notes. This determines the scope and risk level of the upgrade.

Key questions to assess:

• Does this update contain breaking changes?
• Are workflow rules dependent on the old behaviour?
• Do we need additional testing or stakeholder approval?
• Is the update required or optional?

Step 2 — Create an Upgrade Branch or Environment

To ensure safety, upgrades occur in an isolated environment separate from production. This allows schema changes and UI updates to be tested without affecting live users.

This step typically includes:

• creating a Git branch dedicated to the upgrade
• provisioning a staging environment
• setting up test data or copying anonymised production data

Step 3 — Apply the System Upgrade

The Project’s pinned version is updated to the new system version. Files, UI components, backend logic, and configuration from the new version replace or extend the existing installation.

This may involve:

• installing a new version of the system package
• merging or overwriting system-provided files
• updating configuration defaults if necessary

At this stage, the Project is running the new system version, but it has not yet been validated.

Step 4 — Apply Schema Migrations

If the new version contains schema changes, they must be merged into the Project’s unified schema file and migrated to the database.

Each system provides:

• a Prisma model fragment
• a set of Prisma migrations

During an upgrade, these migrations are applied in sequence while ensuring:

• existing data remains compatible
• relations are preserved
• downtime is avoided

Step 5 — Validate Functionality in Staging

Before approving the upgrade, maintainers validate that the new system version behaves correctly in a staging environment.

Validation may include:

• testing UI flows for regressions
• ensuring backend logic and automations function correctly
• running test suites
• reviewing error logs and monitoring tools

Step 6 — Workflow Layer Checks

Because each Project includes partner-specific logic on top of the systems, workflow compatibility must be verified after every upgrade.

Checks typically include:

• verifying custom business rules still pass
• ensuring custom UI still works with updated components
• confirming third-party integrations behave as expected

This step is essential for preserving the uniqueness of each Partner’s platform.

Step 7 — Approve and Deploy the Upgrade

Once all tests are passed, the new system version can be deployed to the production environment. This includes any schema migrations that were previously applied in staging.

This deployment:

• updates production code
• runs any final migrations
• activates the new system version in live environments

After deployment, the Project is now officially using the upgraded system version.

Step 8 — Update the Project’s Version Map

The final step is updating the Project’s internal record of which system version is now in use.

The version map becomes:

• auth-system: 1.3.0 (updated)
• onboarding-system: 0.5.4
• quote-engine: 0.9.1
• notifications-system: 0.3.2

This record ensures ongoing clarity, auditability, and maintainability.

Rollback Procedure

If validation fails at any stage, the upgrade can be safely rolled back because:

• the previous pinned version remains fully intact
• schema migrations can be reverted if needed
• the Project codebase still contains the previous system files

This prevents downtime and ensures sensitive partner workflows remain unaffected.

Summary

The Upgrade Path Process is a controlled, repeatable workflow for safely adopting new versions of Business Systems. Through staged testing, schema merging, workflow validation, and explicit approval, Projects evolve without risking stability. System upgrades are always opt-in, always transparent, and always guided by clear documentation, ensuring Partners remain confident in the evolution of their platforms.