An engineer asks for a "system-design diagram" of your inventory service. Another asks for its "architecture diagram." Sending both the same picture may be reasonable, but the names alone do not tell you what either person needs. One might be deciding whether checkout can trust a displayed stock count. The other might need to change how reservations expire. Those decisions require different relationships on the page.
The names overlap; the questions do not
People use architecture diagram and system-design diagram for much the same family of drawings: components of a system and the relationships between them. Neither name fixes a level of detail. An architecture diagram can show the system's surroundings, its running services, its code modules, or where those services run. A system-design diagram can do the same. Asking which label is correct will rarely settle which boxes to draw.
Start with the reader's question and choose the smallest view that can answer it. The Software Engineering Institute's Views and Beyond book record describes choosing what information to document before deciding how to express it. Its guidance treats views as part of architecture documentation, not as competing names for a single universal picture. That is useful here, but it is guidance, not evidence that any particular diagram improves a team's performance.
Consider a fictional inventory service for an online shop. Checkout asks the inventory API to reserve units of a product. The inventory API writes the reservation and available quantity to its database in one transaction. A separate worker expires reservations that were never purchased. The product page reads a cached availability number, which may lag behind the database. These are assumptions for the example, not a proposed design for every shop.
The checkout engineer needs the running path
The checkout engineer asks, "Can checkout trust the product-page number when it attempts a reservation?" Draw a view of the running interactions. Include the product page, its availability cache, checkout, the inventory API, and the inventory database. Label the product-page arrow as a cached read and the checkout arrow as a reservation request. Show that the reservation succeeds or fails against the database's current state, not against the displayed number.
That view exposes the relevant answer. A cached number is a hint; a successful reservation temporarily allocates stock under this example's reservation rules. If the cache refreshes late, customers can see a positive number and still receive a reservation failure. The diagram should show that failure response returning to checkout. Without it, an arrow from checkout to inventory looks like a guarantee of success.
A box called "Inventory" between "Website" and "Database" would hide the distinction. It gives no clue that the website makes two different requests with different freshness and failure behavior. A deployment map showing regions and servers would be more detailed in another direction, yet still leave this engineer's question unanswered. The useful scope is the request and data path around the stock decision. It need not show every service in the shop.
This view still cannot establish that the transaction prevents overselling. That claim needs the reservation rules and evidence from the implementation or tests. The diagram tells the team where to inspect and which assumption to challenge.
The engineer changing expiry needs code responsibilities
Now an engineer must change the reservation expiry policy. The running path shows that a worker touches inventory data, but it does not tell them where the policy lives or which code depends on it. Draw a view of responsibilities inside the inventory code. For this example, show a reservation policy module that decides when a reservation expires, a reservation store that reads and writes records, the API handler that creates reservations, and the expiry worker that finds candidates and invokes the policy. An arrow here means "calls or depends on," not "sends a network request."
That distinction matters. If both the API handler and worker implement their own expiry rule, changing only the worker could leave two definitions of an active reservation. A module view makes that duplication visible as a design question. If the rule belongs in one policy module, the engineer can ask whether both callers use it. The view should say who owns the rule and which components use it; a wall of individual classes would bury that decision.
The code view cannot answer the checkout engineer's freshness question. It might show a cache adapter without revealing when the product page reads from it, when the cache updates, or what happens when a reservation fails. Combining all those runtime arrows with every code dependency would make the relationship labels ambiguous. Keep the two views linked by shared names such as "inventory API" and "expiry worker," then let each view answer its own question.
The SEI's review guidance by Nord and colleagues centers the intended stakeholders and whether the documentation gives them enough information to do their jobs. This example applies that idea at a small scale: ask each engineer to use the drawing for their actual decision. If they must supply the key relationship verbally, add it or change the view.
Choose the view, then name its relationships
Before drawing, write one sentence above the canvas: "This view helps [reader] decide [question]." For the checkout engineer, the boxes are running components and the arrows are requests and data movement. For the expiry change, the boxes are code responsibilities and the arrows are dependencies. Put that meaning in a small legend or in direct arrow labels. "Reads cached availability," "reserves against current stock," and "calls expiry policy" carry more information than identical unlabeled lines.
You may later need a view of external systems or deployment locations. Draw one when a reader has a question about a boundary, ownership, hosting, or failure location that the current view cannot answer. Bellomo's SEI report on documenting service-oriented systems adapts a view-based documentation approach for a specific kind of system; its larger point is to tailor documentation to the concerns at hand. It does not make a complete set of views mandatory for every conversation.
If someone asks for an "architecture diagram" tomorrow, ask what they need to decide. You can then choose the relationships that make the answer visible, and leave the rest for a different view when a different question arrives.
For the checkout question, you could use Lycana to sketch the cached product-page read and the reservation request with spoken or typed instructions, then edit the connections until the failure response is clear. A separate code-responsibility drawing would serve the expiry engineer's question; changing the label on the first drawing would not supply those dependencies.
