Architecture as Prose

A useful architecture diagram can read like a sentence: someone acts, something changes, and there is a result. Naming those parts makes the system easier to discuss before we get into its implementation.

For example: an instructor records attendance; the system updates the class register. That sentence identifies an actor, an action, and the information affected. It also gives us questions to ask. Who can record attendance? What happens if the update fails? Which part of the system owns the register?

A box labeled “API” answers few of those questions on its own. Labels on the connections can do more work: records, validates, stores, or notifies. Each verb describes a responsibility that needs a clear owner.

Complex systems need more than one sentence or one diagram. A simple account of the main workflow gives the detail a place to belong. Separate views can then explain permissions, failure paths, and infrastructure without obscuring the action people care about.

If we cannot explain the main actions clearly, we revisit the design before adding detail. The aim is an explanation that helps the team ask better questions and make the next decision.