Skip to content
DT Nova

Software architecture: definition, patterns, diagrams and good practice

Software architecture is the structure of a system and the decisions behind it: which parts it consists of, what each part does, how the parts communicate, where data is stored and how it all runs in production. Good software architecture makes the system easy to change where the business changes often and stable where it must not break. This guide explains what software architecture is, the main patterns, how to draw and document it, and the practical choices that matter most for a company commissioning a system.

Sources were read on 12 November 2026: the IEEE SA page for IEEE/ISO/IEC 42010-2022, the C4 model site, the arc42 overview, Martin Fowler and James Lewis's article on microservices, and Regulation (EU) 2024/2847 (Cyber Resilience Act).

Software architecture: the definition

The international standard for describing architecture is IEEE/ISO/IEC 42010, whose current edition was published on 7 November 2022 and is listed by IEEE SA as an active standard. It specifies requirements for the structure and expression of an architecture description for software, systems and enterprises. In plainer words: architecture is what the system is made of and why, and the description is how you explain that to the people who pay for it, build it, run it and audit it.

A practical test separates architecture from everyday design: an architectural decision is one that is expensive to reverse. Choosing the database engine, splitting the system into services, deciding that the mobile app talks to one API rather than to five, choosing to host in an EU region, deciding how users log in. Choosing a name for a function is not architecture. Choosing whether invoices are calculated in the browser or on the server is.

What architecture decides

  • Building blocks. The parts of the system and the responsibility of each: user interface, API, business logic, background jobs, integrations, reporting.
  • Data. Which database holds what, which part owns which data, how long it is kept and how it is backed up.
  • Communication. How parts exchange information: direct requests, messages on a queue, files, events.
  • Deployment. Where each part runs, in which region, with what redundancy, and how new versions reach production.
  • Quality attributes. The non-functional goals that shape everything else: response time, availability, security, scalability, maintainability, accessibility and cost of running.
  • Cross-cutting concerns. Login and permissions, logging, error handling, translations, audit trails.

Quality attributes deserve the most attention, because they are rarely written in a requirements list and they decide the architecture. A system that must work offline in a warehouse, a system that must keep a tamper-proof audit trail and a system that must handle a sales peak ten times the normal load need different structures even if their screens look alike. Our software requirements specification guide shows how to write these requirements so they can be tested.

The main architecture patterns

PatternWhat it isFits when
LayeredPresentation, business logic and data access in separate layers.Classic business applications with forms, rules and a database.
Modular monolithOne deployable application, divided internally into modules with clear boundaries.Most new business systems: fast to build, simple to run, ready to split later.
MicroservicesMany small services, each deployed and scaled on its own.Large systems with several teams, parts with very different load, frequent independent releases.
Event-drivenParts react to events published by others through a message broker.Integrations, workflows across systems, real-time updates, IoT.
ServerlessFunctions run by the cloud platform on demand, no servers to manage.Irregular load, background processing, small APIs.
Hexagonal (ports and adapters)Business logic in the centre, databases and external services plugged in through interfaces.Systems with complex rules and many integrations that change over time.

Martin Fowler and James Lewis, in their 2014 article that popularised the term, describe the microservice style as an approach to developing a single application as a suite of small services, each running in its own process. The style has real costs that are easy to underestimate: a distributed system is harder to test, monitor and keep consistent than one application. For a company system with one team, a modular monolith with well separated modules gives most of the benefits without those costs, and keeps the option of extracting a service when a real reason appears.

Monolith or microservices: the honest answer

The question comes up in almost every project, often because a vendor or a job advert made microservices sound like the modern default. The deciding factors are organisational more than technical:

  • Number of teams. Services help several teams release independently. One team gains little and pays the coordination cost anyway.
  • Uneven load. If one function (search, image processing, a public API) needs a hundred times the capacity of the rest, run it separately.
  • Different rates of change. A pricing engine that changes weekly and an accounting export that changes yearly can live in different deployable units.
  • Operations maturity. Many services need automated deployment, central logging, tracing and monitoring from the first day.

Our default for new systems is a modular monolith with a clean API, automated tests and infrastructure defined as code. It is the structure that is fastest to build and simplest to run, and the module boundaries are drawn so that a part can become its own service without rewriting the rest.

The software architecture diagram

A software architecture diagram is only useful if the reader understands it without the author in the room. Boxes and arrows without a legend rarely pass that test. The C4 model, a freely licensed approach created by Simon Brown, solves this with a set of hierarchical abstractions (software systems, containers, components and code) and matching hierarchical diagrams: system context, containers, components and code. Each level zooms into the previous one:

  1. System context: your system as one box, the people who use it and the other systems it connects to. Readable by management.
  2. Containers: the applications and data stores inside: web app, mobile app, API, database, message queue. The level most teams need.
  3. Components: the main parts inside one container. Useful for complex containers only.
  4. Code: classes and functions, best generated from the code itself when needed.

Most systems are documented well enough with the first two levels plus a deployment diagram that shows where things run: cloud regions, managed services, network boundaries. Keep diagrams in the repository as text-based diagram files, so they change in the same pull request as the code they describe.

Documenting architecture: arc42 and decision records

arc42 is a free, open source template for architecture documentation, also for commercial use, in use since 2005. It has twelve sections, from goals and constraints through context, building blocks, runtime and deployment views to decisions, quality requirements, risks and a glossary. It is tailorable: a small system can fill five sections in a few pages, and arc42 also offers a one-page canvas for a quick overview.

The most valuable section in practice is the decision log. An architecture decision record is a short note per decision: the context, the options considered, the decision, and its consequences. Two years later, when someone asks why the system uses a queue instead of direct requests, the answer is in the repository rather than in the memory of someone who left. A decision record also makes it easier to revisit a decision deliberately when the context changes.

Security and the law: architecture is where it starts

Security cannot be added at the end; it follows from structure. Where data is stored, which part can read what, how secrets are managed, how updates reach users. The Cyber Resilience Act, Regulation (EU) 2024/2847, makes this a legal matter for products with digital elements sold in the EU. Its essential requirements, listed in the Regulation's annex, say products shall be designed, developed and produced to ensure an appropriate level of cybersecurity based on the risks, to limit attack surfaces, and so that vulnerabilities can be addressed through security updates. The Regulation applies from 11 December 2027, with the reporting obligations of Article 14 applying from 11 September 2026. Our Cyber Resilience Act guide covers who is affected. Data protection works the same way: data protection by design, required by Article 25 GDPR, is mostly an architectural property, decided by what is stored, where and for how long.

Scalability and performance without overbuilding

Architecture for scale is often bought too early. A business system for a few hundred users does not need the structure of a consumer platform. What it needs is a design that can grow in known steps: stateless application servers that can be multiplied, a database with room to grow and read replicas when reporting gets heavy, a cache for expensive queries, background jobs for slow work, and monitoring that shows where time goes before anyone guesses. Measure first, then scale the part that is actually slow.

Good practice for companies commissioning software

  • Write quality requirements down. Availability, response times, data retention, number of users in three years. They decide the architecture.
  • Ask for the context and container diagrams before development starts, and for an updated version at handover.
  • Keep decisions recorded in the repository, with the reasons.
  • Prefer boring technology that many teams know, so you are never tied to one supplier.
  • Own the accounts. Code repository, cloud account and domain in your company's name.
  • Plan for maintenance. Every framework and runtime has an end of support date; see our technical debt guide and software maintenance.

How we work on architecture

Every system we build starts with a short architecture phase: quality goals, a context and container diagram, the hosting plan in an EU region and the first decision records. They are delivered in the repository in your company's account with the code, so any competent team can take over. We also review existing systems: what the architecture actually is today, where it limits the business and which changes pay back first. See custom software development and software consulting.

Questions people ask

What is software architecture in simple terms?

Software architecture is the set of big decisions about how a system is built: which parts it has, what each part is responsible for, how the parts talk to each other and where the data lives. They are the decisions that are expensive to change later, which is why they deserve to be made on purpose and written down.

What is the difference between software architecture and software design?

Architecture covers the structure of the whole system and the decisions that are costly to reverse: the split into parts, the database, the hosting, the integration style. Design covers how each part is built inside: classes, modules, functions and screens. The line between them is not sharp, but a good rule is that architecture decisions affect several teams or several years.

Should a new system use microservices?

Usually not at the start. A well structured modular monolith is faster to build, easier to test and simpler to run. Splitting into services makes sense when parts of the system need to scale, be released or be owned by teams independently. A clean modular structure makes that split possible later without a rewrite.

What should a software architecture document contain?

At minimum: the goals and quality requirements, the context (users and neighbouring systems), the main building blocks, how the system is deployed, and the key decisions with the reasons behind them. The arc42 template organises this into twelve sections; small systems can use far fewer.

Who owns the architecture when an agency builds the software?

You should. The architecture documents and decision records belong in the same repository as the code, in your company's account, so another team can understand and continue the system. That is our standard term.

Sources