An old architecture diagram can answer the wrong question very convincingly. A new engineer sees an arrow from the Catalog API to the catalog database and concludes that every product search reads that database. Last month, the team moved most searches to an index. The arrow still describes the source of product records, but it now gives the wrong answer about the live search path.

Consider a fictional shop making that migration. The diagram is a request-flow view for engineers changing search and investigating slow queries. It deliberately leaves out authentication, deployment, and the rest of the shop. Its job is to show where a search request goes and which system answers it.

First revision: show the change before it is complete

In the original system, the browser sends a search request to the Catalog API. The API queries the catalog database and returns matching products. The diagram labels that arrow as a search read, rather than leaving a line that might also mean a write or a schema dependency. Someone investigating a slow search can see why database query performance might affect the response.

The team builds a search index and starts a pilot. Most requests still use the database. A small group goes through the API to the new index. A diagram that replaces the database arrow with an index arrow at this point would be tidy and false. Both read paths exist. The revised view shows both, labels who takes each path, and links the rollout decision that says when traffic may move. It also records an open question: how quickly must a catalog edit appear in index results?

This is the first maintenance choice: the diagram follows the system's operating state while the planned architecture remains a separate decision. The extra arrow makes the drawing busier for a while. Hiding it would make a slow-query investigation harder, because the affected request could have used either path.

Second revision: retire an arrow, retain its reason

After the team moves all search traffic to the index, the Catalog API no longer queries the catalog database to answer normal searches. The current request-flow view shows the browser, Catalog API, and search index. It labels the API-to-index arrow as the live search read. The database still owns product records, so the view includes a small note pointing to the separate index-update flow. The team needs to verify how edits reach the index and how it handles lag or missed updates. An arrow between the database and index would not establish those guarantees.

The database-read diagram still has a use. It explains old query traces and the reason for the migration. Keep it as a dated historical view linked to the rollout decision. Do not leave it as the first diagram in the search runbook. In that position, it would send an on-call engineer toward database query plans when the slow request actually waited on the index.

Research on documentation gives a useful caution here. In three studies reported in 2003, Lethbridge, Singer, and Forward found that engineers did not always update documents when systems changed, yet older documents could still help, especially when higher-level explanations remained valid. Their studies do not provide an expiry date for a diagram. In this example, the old view remains useful as history; it becomes misleading when presented as the current search path.

Third revision: narrow the view when the question changes

Suppose the next change adds a fallback. If the search index times out, the Catalog API queries the database for a limited search and marks the response as degraded. The request-flow view must show that conditional arrow back to the database. Without its label, someone could mistake the fallback for the normal path. A separate index-update view can show how product edits reach the index, where lag is observed, and how a failed update is repaired. Putting all of that detail into the search request view would force readers to sort through data maintenance before finding the response path.

The SEI's Views and Beyond guidance treats an architecture view as selected system elements and relationships, chosen according to how people will use the documentation. That is a useful test for this split. An engineer tuning the API needs to know which path answers a request. An engineer maintaining the index needs to know how product changes reach it. Both views describe the same system, but neither needs to carry every detail.

Make the next change easy to catch

For this migration, the Catalog API team owns the search request view because it owns the routing choice the view promises to explain. The Search team owns the detailed index-update view. That division is only useful if a cross-team change names who updates both views. The rollout work item should include the affected diagram links and a review when pilot traffic changes, when database reads are retired, or when fallback behavior changes. A calendar reminder can catch neglect, but the change itself is the stronger trigger.

Each current view should state its scope, its owner, and what it was last checked against, such as the rollout decision and the deployed routing configuration. Record the check date as provenance, not as a guarantee that every arrow remains correct. If the owner cannot verify a path, mark that uncertainty beside the relationship instead of letting the drawing imply certainty. A reader can then tell the difference between a known route, an intended route, and one that needs inspection.

This approach costs a little attention during changes. It also asks teams to preserve a historical view and a current one without confusing their purposes. For a small system with one obvious path, one well-labeled current diagram and a decision link may be enough. For a migration with two live paths, simplifying too early is the expensive choice. The useful test is whether a colleague can follow today's search request, including its fallback, and know where the diagram stops making claims.

If the request-flow view lives in Lycana, use a spoken or typed instruction to revise the Catalog API's search relationship when traffic moves, then inspect the canvas against the deployed routing configuration. Edit the fallback arrow only when that path exists. The tool can hold the revised drawing; the owner still has to check which route is live.