System architecture

Teams write down a system architecture so that everyone building, running and paying for a system agrees on what it is. Once the structure is explicit, every later decision, from database choice to incident ownership, has something to be checked against.

What does system architecture include?

• Components. The major parts: applications, services, data stores, queues and the external systems the system depends on.
• Interactions. Which components talk to which, over what protocol and in which direction.
• Deployment. Where each component runs: devices, regions, clusters, managed services.
• Boundaries. Trust boundaries, network zones, team ownership and the edge of the system.
• Quality attributes. The measurable properties the structure is meant to deliver, and the trade-offs made between them.
• Decisions. Why the structure is the way it is, recorded as architecture decision records.

A system architecture names which architecture patterns the system uses and where: three-tier at the deployment level, say, with microservices or a monolith inside the application tier and MVC inside a web service.

How do you read a system architecture diagram?

Start with the users and follow the arrows. In the logistics platform at the top of this page, the clients of this client-server system are shippers, drivers and warehouse staff, who all enter through the edge: a web application firewall and CDN for the portal and an API gateway for every API call. The gateway routes to three application services that own shipments, routing and tracking.

Each service owns a data store. The shipment service writes PostgreSQL, routing writes route files to object storage and tracking publishes location events to Kafka, which streams into the analytics warehouse. External systems sit on the right and are reached only through the integration layer, so a change to a carrier’s API touches one adapter rather than every service. Carrier webhooks come back in through the gateway. The operations band holds monitoring, logging, CI/CD and secrets, which every tier uses and no tier owns.

What are architecture views and viewpoints?

No single diagram can show a system to every reader. A view is one diagram that answers one set of questions. A viewpoint is the convention for drawing that kind of view: its elements, notation and audience. ISO 42010 formalizes the terms, and Kruchten’s 4+1 model is the best-known set of views.

View	Question it answers	Typical diagram	Reader
Logical	What are the parts and how do they relate?	Component diagram, C4 container diagram	Engineers, architects
Process	How does work flow at runtime?	Sequence diagram, data flow diagram	Engineers, performance reviewers
Deployment	Where does each part run?	Deployment diagram	Operations, security
Data	What is stored and who owns it?	Entity-relationship diagram, ownership table	Data engineers, compliance

The C4 model is a practical viewpoint for the logical view at four levels of zoom, starting with a context diagram. Pick the views the system’s readers need and keep the same component named the same way in every view.

What are quality attributes?

Quality attributes are the measurable properties a structure is chosen to deliver: availability, performance, scalability, security, maintainability, observability, cost and compliance. An architecture is good or bad only relative to the attributes it targets.

Attributes trade against each other. Caching improves performance and complicates consistency. Splitting services improves deployability and hurts debuggability. The architecture should say which attributes win and the decision records should say why.

How does system architecture compare with system design and software design?

Term	Scope	Output
System design	The activity of choosing a structure for given requirements	Trade-off analysis, candidate designs, decisions
System architecture	The structure chosen, including hardware, networks and external systems	Views, diagrams, decision records
Software architecture	The software part of the system architecture	Service and module structure, interfaces
Software design	The structure inside one component	Class diagrams and interfaces
Solution architecture	How several systems combine to solve one business problem	Integration diagrams, product choices

How do you define a system architecture?

1. Write down the quality attributes. Pick the few that matter, with numbers: 99.9% availability, under 300 ms for a tracking lookup, data resident in one region.
2. Draw the context. The system as one box, its users and the external systems it depends on. This fixes the boundary.
3. Identify the components. Split the system by what changes together and is owned together.
4. Define the interactions. For every connection, name the protocol, the direction and what happens when the other side is down.
5. Place the components. Decide where each runs and draw the deployment view.
6. Check against the attributes. Walk a failure, a traffic spike and a security review through the diagrams.
7. Record the decisions and keep the views current. Store the diagrams with the code, ideally as diagram as code.

What are common system architecture mistakes?

• One giant architecture diagram. Everything on a single page serves no reader. Split into views.
• No quality attributes. Without targets, every design is defensible and none can be checked.
• Hidden external dependencies. The payment provider is part of the system’s availability whether it is drawn or not.
• Forgetting operations. Monitoring, deployment pipelines and secrets are components too, and they fail.
• No decision records. A diagram tells the next team what, but never why.

What tools can you use to document system architecture?

• Modeling tools. Tools built on ArchiMate or SysML hold one model and generate every view from it, at the cost of a steeper learning curve.
• Diagram-as-code tools. Text descriptions of each view, kept in the repository and reviewed in pull requests. See the best diagram-as-code tools for a comparison.
• AI diagramming tools. Tools like Eraser turn a description of your system, a design document or infrastructure code into a system architecture diagram you can keep editing, which makes several views practical to maintain.

For more on this kind of diagram, see architecture diagrams.

Frequently asked questions