Good Software Architecture Is About Decisions, Not Diagrams

Diagrams Are Views, Not Decisions

A diagram is a view. It selects a perspective, hides details and emphasizes relationships that matter to a particular reader. ISO/IEC/IEEE 42010 describes architecture descriptions through stakeholders, concerns, viewpoints and views, which is a useful reminder that no single picture captures the whole architecture. ^[1]

Two systems can look similar on a slide and be architecturally different. A box labeled “API” may exist to isolate customers, protect latency, support independent releases or merely organize code. Without the reasoning, the same box can mean discipline, ceremony or accident.

This is especially risky when a diagram travels farther than the conversation that produced it. A stakeholder may see a clean separation and assume the team has already decided ownership, failure behavior and release boundaries. An engineer may see the same separation and assume only package organization. The view is shared, but the decision is not.

This is why architecture reviews that begin and end with pictures often create false confidence. The representation is neat, but the deciding knowledge remains implicit. A useful diagram should help a reader find the decisions; it should not pretend to replace them.

Architecture Begins With Forces

A decision is not architectural because it involves an important technology. It becomes architecturally significant when it shapes quality attributes, boundaries, dependencies, data ownership, deployment, security, operations, cost of change or future capability.

The forces behind a decision are the pressures it must balance: product goals, users, team capacity, time, security, performance, maintainability, compliance, cost and uncertainty. Perry and Wolf’s early work on software architecture connects structure with elements, form and rationale; the rationale is the part that explains why structure exists. ^[2]

Calling these forces out changes the conversation. Instead of asking whether a team “uses microservices,” “uses serverless” or “has clean architecture,” the review asks which pressure the decision responds to and what it makes easier or harder.

Good Architecture Is Contextual

There is no good architecture in the abstract. A simple deployment can be responsible for a small team validating a first version. The same deployment can become reckless when failure isolation, independent delivery, regulatory separation or operational growth become real constraints.

The same decision can be responsible in one context and reckless in another. A shared database can be a practical early simplification or a source of coordination pain. A separate service can protect autonomy or create operational work the team cannot yet handle.

Context does not excuse weak thinking. It gives the decision a frame. The architectural question is not “Is this pattern modern?” but “Does this choice fit the forces we actually have, and what would make it stop fitting?”

That framing also protects teams from premature regret. A decision can be imperfect and still be professionally responsible if it is explicit, reversible enough for the risk level and honest about its review trigger. Architecture work is not the art of avoiding all future change. It is the discipline of making today’s commitments understandable to tomorrow’s team.

Quality Attributes Turn Opinions Into Questions

Words such as scalable, secure, maintainable, fast and reliable are too broad to guide architecture unless they become observable scenarios. “The system must scale” is weaker than asking what change in traffic, data or workload the system must absorb, within what response time, recovery target and cost envelope.

SEI’s architecture evaluation work, including ATAM, treats architecture as something evaluated against quality attributes, risks, sensitivity points and trade-offs rather than aesthetic preference. ^{[4] [5]}

That shift matters. Instead of “the system must be maintainable,” ask what kind of change a team should implement without touching unrelated modules. Instead of “the system must be reliable,” ask which user-visible operation must survive which dependency failure and how the team will know.

Operational objectives such as SLOs are useful because they make reliability discussable in measurable terms. They do not replace architecture, but they help decisions stay connected to the behavior the system must demonstrate. ^[9]

Boundaries Are Decisions About Change

Boundaries are often drawn as lines between boxes, but the stronger question is what change the line is protecting. Parnas argued for decomposing systems around information hiding rather than merely following processing steps, because modules should conceal decisions likely to change. ^[3]

That idea is still practical in modern systems. A payment provider adapter protects provider change. Authentication boundaries protect security policy and identity flow. A mobile platform capability boundary protects the app from differences between native APIs. An AI model provider boundary protects the product from treating a vendor response as a permanent domain model.

None of these boundaries automatically require a microservice. A logical boundary can live inside a single deployable unit. The architectural value comes from ownership, dependency direction and change isolation, not from the number of processes.

Every Decision Creates a Consequence

Architectural decisions buy something and pay something. A shared database can simplify reporting and transactions while increasing coupling. Microservices can support autonomy under the right conditions while adding distribution, observability and operational burden. Managed services can reduce undifferentiated operations while introducing limits, cost and provider dependence.

Cross-platform mobile development can share implementation, but it does not remove native platform differences. AI integrations can handle language and ambiguity, but they introduce probabilistic behavior, evaluation needs, cost controls and failure modes that deterministic workflows may not have.

The mature conversation is not “Should we use X?” It is “What does X make easier, what does it make harder, and what evidence says that trade-off is acceptable here?”

Consequences should be written in both directions. A decision record that only lists benefits is advocacy, not architecture. A useful record names the pain the team is choosing so that nobody is surprised later when that cost arrives.

The Istio Lesson: Architecture Can Be Reversed

The Google Research report on Istio’s move from a microservices architecture toward a consolidated monolithic architecture is useful because it resists slogans. The lesson is not that microservices are bad. The lesson is that a decision that once seemed reasonable can become less attractive when operational evidence changes. ^[8]

In that case, the team evaluated real costs and difficulties, then changed course. That is architectural maturity: not defending a diagram because it looks sophisticated, but revisiting a decision when consequences become clearer.

A healthy architecture practice keeps enough rationale to reverse itself honestly. It can say, “This decision fit the forces then; these forces are different now.”

That sentence is harder to say when the original decision was only a diagram or a meeting memory. It becomes much easier when the team can point to the context it believed, the consequence it accepted and the evidence that later changed.

Document the Why, Not Only the What

Architecture Decision Records are one lightweight way to preserve reasoning. Michael Nygard’s original ADR essay emphasizes recording status, context, decision and consequences close to the work where future teams can find them. ^[7]

The useful part is not bureaucracy. It is memory. An ADR records what alternatives were considered, what the team chose, what cost it accepted and how a later decision can supersede it without pretending history was different.

Not every decision deserves an ADR, and an ADR should not become a long essay. It should be just enough to let a future engineer understand why the code, deployment, boundary or dependency looks the way it does.

A Diagram Should Point to Decisions

Diagrams are useful when they are honest about their job. A diagram can show elements, relations, boundaries, flows, deployment and perspective. A decision record explains context, alternatives, choice and consequences. A quality scenario defines what the system must achieve. Code and telemetry show whether the decision is real.

SEI’s Views and Beyond material is valuable here because it treats architecture documentation as a set of views serving different readers and concerns, not as one universal artifact. ^[6]

The strongest architecture documentation connects these artifacts. A reader can move from a diagram to the decision behind a boundary, from that decision to the scenario it protects, and from the scenario to code, tests or telemetry that demonstrate it.

Architecture Must Survive Contact With Code

A decision that exists only in a presentation does not govern a system. It must become visible in repository structure, module boundaries, dependency rules, interfaces, data ownership, deployment, security controls, tests, observability, CI/CD and review practices.

Folder structure alone does not prove architecture. But if the stated boundary cannot be found in code, tests or operations, the team should ask whether it is a real decision or only a drawing convention.

The point is contrast. The team should be able to compare the decision it claims to have made with the system it is actually operating.

This is where architectural governance becomes practical instead of ceremonial. Code review can ask whether dependency direction matches the intended boundary. Observability can show whether the failure mode assumed by the decision is real. Deployment history can reveal whether independent release was a benefit or just a drawing.

Architecture Is a Living Hypothesis

Architecture is a hypothesis about how a system can satisfy its goals under known constraints. It should be reviewed when users, workload, team structure, regulation, providers, cost, product direction, risks or operational evidence change.

This does not mean architectural churn. Evolution is a disciplined response to evidence. Churn is changing structure because the team is bored, anxious or following fashion.

The practical question is simple: what observation would make this decision less true? If there is no answer, the decision is probably not understood well enough.

A Practical Decision Framework

Context → Forces → Decision → Consequences → Evidence → Review trigger

A practical frame I use to test architectural decisions has six parts. Context asks what problem exists and under which constraints. Forces identify the goals or pressures competing for attention. Decision states the option chosen in concrete terms.

Consequences name what the choice enables, what it makes harder and what cost it creates. Evidence records the information, prototype, metric, source or experience behind the choice. Review trigger defines the future change that would justify reconsidering it.

This frame keeps architecture grounded. It prevents a diagram from being the final answer and turns “we chose this pattern” into a reviewable, revisitable decision.

It also scales down. A small team does not need a heavyweight architecture board to use it. One short decision note in the repository can be enough when the choice affects boundaries, data, operations or the cost of future change.

Field Notes From Real Products

Public project evidence is intentionally narrower than private project experience, so the responsible move is to stay inside what is confirmed. Bozz Apps is published as a mobile and web platform connected to commercial sales workflows, with mobile application, backend/platform and case-study evidence available on this site.

A platform like that is not defined only by a diagram that says mobile → API → dashboard. The decisions that matter are closer to responsibility: which workflows belong in the mobile app, which responsibilities belong in backend services, how application and platform contracts evolve, and what information must remain stable as workflows change.

That is enough to illustrate the point without inventing offline behavior, metrics, client outcomes or private incidents. The field note supports a lesson: product architecture is found in boundaries and consequences, not in a prettier drawing.

Warning Signs of Diagram-Driven Architecture

Teams drift into diagram-driven architecture when they discuss boxes more than goals, choose technology before defining the problem, forget the alternatives, or give every component an architectural name while rules and data remain shared without clear boundaries.

Other warning signs are equally practical: “scalable” appears without a scenario; the diagram changes but the code does not; the code changes but the diagram does not; nobody owns the decision; nobody knows when to revisit it.

The issue is not that the team uses diagrams. The issue is evaluating the system by its appearance rather than by the consequences of its decisions.

A Checklist for Reviewing an Architectural Decision

• What problem does this decision solve?
• Who is affected by it?
• Which quality attributes matter?
• What alternatives were considered?
• Which trade-off are we accepting?
• Which boundary does the decision create or protect?
• How will the decision appear in code and operations?
• How will we know whether it works?
• What could invalidate it?
• Where is the rationale recorded?
• Who owns its evolution?
• Can the team explain it without the diagram?

Conclusion

Return to the room with the impressive diagram. It may still describe a weak architecture if the team cannot explain context, decisions, trade-offs, evidence and conditions for change.

A modest diagram can represent a strong architecture when the team understands why the system has that shape and how the decision will be tested in code and operations.

Good architecture is not the picture of a system at rest. It is the recorded judgment of how a team chose to let that system change.