Separate identity from display
Give each architectural item a stable, non-semantic identifier. Keep its human-readable title editable. For example, APP-0042 can remain the same element while the display name changes from “Partner Portal” to “External Services Portal”. Relationships continue to point to the identity, not the old label.
Use display keys for comprehension, not referential integrity
A source–integration type–destination description is excellent for browsing an integration register. It is not necessarily unique forever: endpoints may change and parallel integrations may exist. Keep a separate immutable record ID and make the description a derived or maintained display field.
Protect relationships and historical meaning
Applications can have consumers, providers, technology dependencies, API contracts and project revisions. When an element is renamed, these connections should survive. If an element truly splits into two successors or is superseded, represent that as an explicit lifecycle or lineage event rather than recycling the old ID.
Make imports idempotent
A repeat import should update or recognise the intended records, not create duplicates because a spelling changed. Mapping stable external keys to internal IDs, using controlled identity reconciliation and reporting exceptions helps preserve trust in a growing catalogue.
A small modelling rule with a large payoff
Never make a UI label carry the burden of being the canonical identifier. This improves search, exchange, visualisation, migration and long-term auditability.
Strong architecture practice depends on precise models, explicit ownership and decisions that remain useful as systems change. Examples are fictional and are presented as architectural guidance.