Stable abstractions vs. version-specific elements: best practices for architecture modeling

[thinkscape-gmbh]

Stable abstractions vs. version-specific elements: best practices for architecture modeling

I’m trying to understand the best way to model applications, interfaces, and their implementations so that the architecture remains understandable and manageable as implementations are replaced.

Consider a client application that currently uses Service API v1 and will eventually migrate to Service API v2. I see two possible modeling approaches.

Approach 1: Stable logical elements with versioned implementations

In this approach, business applications and interfaces represent stable logical concepts, while IT components represent their concrete implementations.

For example:

• Business Application: Client Application
  • Realized by IT Component: Client Application v1
• Interface: Service API
  • Realized by IT Component: Service API v1
  • Later realized by IT Component: Service API v2

The idea is to keep relationships at the logical level where appropriate, while replacing the implementation components underneath. This would allow the business application and interface elements to remain relatively stable across implementation changes.

However, it introduces an additional layer of abstraction, which requires a lot more initial modeling and maintenance. It may also be less intuitive for people who are not familiar with the distinction between logical elements and concrete implementations.

Approach 2: Version-specific elements throughout the model

Alternatively, I could model the versions directly:

• Business Application: Client Application v1
• Interface: Service API v1

This seems more straightforward because each element represents a specific version.

My concern is replacement effort. These elements may have many relationships with other applications, teams, components, and data objects. When introducing a replacement, those relationships would need to be reviewed and potentially recreated or reassigned.

Possible ways to manage replacements

I’m considering a few options, but I’m unsure which would be most appropriate:

• Potential feature request: successor-based relationship transfer: Would it make sense to support marking Service API v2 as the successor to Service API v1 and, when retiring the predecessor, choosing which relationships to transfer to its successor in the UI?
• Bulk updates: Use Excel export/import to update relationships in bulk during a migration.
• Stable logical modeling: Keep business applications and interfaces version-independent, and model versions only at the implementation level.

Thank you!

[FraukeBAG]

Hi @thinkscape-gmbh,
I would always advocate for logical modeling that is as stable as possible, since otherwise the maintenance effort is, in my view, too high.

In other words, I would set up the following:
Business Application: Client Application
Interface: Service API
Implemented by IT Component: Service API v1
Later implemented by IT Component: Service API v2
You could also put relation values on it like "Phase-out", "Active", "Planned"

At the end of the day, you always have to ask yourself: What data—or analyses—do I really need? When in doubt, always start with less, rather than ending up with too much data that just becomes outdated if no one maintains it.