Pinning Systems to Projects

Pinning is the mechanism that ensures every Project in the Innopo Modular Systems Framework (IMSF) runs on a predictable, well-defined set of Business System versions. Instead of automatically receiving updates from the Systems Library, each Project explicitly records the exact version of every system it depends on.

Pinning provides stability, reproducibility, and accountability across all platforms. It ensures that no Project changes unexpectedly when systems evolve.

What Pinning Means

When a system is pinned to a Project, it means:

• The Project uses a specific semantic version of a system (for example auth-system@1.2.0).
• That version will remain in use until an intentional upgrade is applied.
• Even if newer versions of the system exist, the Project remains stable.
• Migration steps, if required, are only run when explicitly chosen.

This is similar to how package managers lock dependency versions, but it is central to how IMSF provides predictable evolution across Partners.

Why Pinning Is Essential

Because Business Systems evolve over time, pinning prevents accidental breaking changes or behavioural drift.

What this ensures:

• Stability: Projects behave the same across development, staging, and production.
• Version clarity: Teams always know which system version is running in which Project.
• Safe upgrades: New versions are only applied after being reviewed.
• Historical traceability: You can always see which version was active at any point in time.
• Partner confidence: Upgrades never occur silently or unexpectedly.

How Pinning Works Inside a Project

Each Project stores a version map – a record of which systems are installed and which versions they use.

This map is stored internally in the Innopo Platform and is visible inside both the Project and Partner dashboards. It acts as the Project’s “technical fingerprint.”

Pinning During System Installation

When a system is added to a Project during assembly (Step 3 of IMSF), the version being installed is recorded immediately.

During installation:

• the chosen system version is added to the Project’s version map
• the schema for that version is merged into the Project schema
• the system’s files (UI, backend, config) are mounted at known locations

No Project ever uses a moving “latest” tag, every version is explicit.

Pinning and Database Schema

One of the most important functions of version pinning is stabilising the database schema. Because each system contributes Prisma models, pinning prevents schema drift.

Pinning ensures:

• Migrations only run when a system’s version changes.
• Breaking schema changes cannot occur without intentional upgrades.
• The exact schema a Project uses can be reconstructed at any time.

Pinning and the Workflow Layer

The Workflow Layer (Step 4) depends on certain system behaviours. Pinning ensures those behaviours don’t change unexpectedly and break Partner-specific logic.

For example:

• An approval flow expects a specific state machine from onboarding-system.
• The quote-engine may rely on a pricing function signature that cannot change.

By pinning system versions, we ensure workflow logic does not silently break when systems evolve.

What Happens When a New System Version Is Released?

When the Systems Library publishes a new version (patch, minor, or major), Projects are notified internally within the Innopo Platform.

Project maintainers can:

• review the changelog
• view migration notes
• compare differences with the pinned version
• schedule an upgrade

Updates are optional. A Project only changes when the team decides to upgrade.

Manual Upgrades

When upgrading a pinned system version, the Platform guides maintainers through the process:

1. Confirm the current pinned version
2. Review the new version’s changelog
3. Apply schema migrations (if required)
4. Validate UI and backend changes in staging
5. Approve the upgrade
6. Deploy the updated version map

This keeps upgrades structured and controlled.

Partner Transparency

Partners are shown which systems their platform uses and the versions installed—but only at a high level suitable for non-technical audiences.

They can view:

• the list of installed systems
• the version of each system
• whether updates are available

This transparency builds confidence while keeping internal details private.

Why Pinning Makes IMSF Scalable

Without pinning, every update to a Business System would risk breaking an existing Project. Pinning provides:

• a stable foundation for rapid development
• long-term maintainability across multiple Projects
• safe adoption of system improvements
• technical traceability across the entire Innopo portfolio

Pinning is what allows Innopo to operate multiple Platforms, across multiple Partners, with confidence and consistency.

Summary

Pinning Systems to Projects is a fundamental part of the Innopo architecture. It ensures each Project runs on a stable, explicit set of system versions, prevents breaking changes from propagating automatically, and enables controlled upgrades supported by clear migration paths. This provides stability for Partners and operational clarity for the Innopo team, making IMSF scalable and predictable.