Defining Solution Architecture

A product’s architecture is shaped by the important decisions you make about its software, data, the infrastructure it will use, and how those parts work together to meet the system’s needs and constraints (Bass et al., 2021). These include decisions about where data is stored, how parts of the system communicate, how the product integrates with other products or systems, where software runs, and how concerns such as security, reliability, and performance are addressed. These requirements are in turn influenced by the organizational needs and the needs of your stakeholders including external stakeholders such as regulatory organizations.

Some of these decisions are relatively easy to revisit, while others become expensive to change once development is underway. For example, if your product must comply with strict privacy regulations, capabilities like data encryption, access controls, and logging and auditing will need to be built into your architecture from the start. Retrofitting these into your product if you didn’t design for them often requires costly rework. As a result, it’s important to identify and capture the core architecture requirements early, before your design commits you to decisions that are difficult to change.

This chapter shows you how to identify architecture requirements, make them specific enough to guide design decisions, and document the resulting design and important decisions.

What are Architecture Requirements?

In this book, I use the term architecture requirements as an umbrella for the requirements that materially influence important architecture decisions, such as performance and availability, data and integration needs, and technical or organizational standards. These are also known as architecturally significant requirements (Chen et al., 2013), but the terminology matters less than becoming familiar with the needs that influence important structural or technology decisions.

To more easily identify architecture requirements, it helps to have a simple mental model of the parts of a product that architectural considerations can affect. One way to do this is to think about the main logical components of the product and how your requirements might shape the way those components are designed and work together.

User interface. This is where people interact with the system, either through web pages, mobile applications, dashboards, voice interfaces, or other interactions. Requirements related to usability, accessibility, consistency, and how easily people need to complete their work can shape how the interface is designed.

Application and business logic. This executes the rules, calculations, and decision-making processes of your product. Requirements related to business rules and workflows drive how work is coordinated, while performance needs may determine where this logic is executed.

Integration and communication. This enables the system to exchange data and requests with other components, services, devices, and external systems through Application Programming Interfaces (APIs), messaging services, integration platforms, data pipelines, and other connections. Requirements for reliability, interoperability, performance, and dependence on other systems can shape how these connections and integrations are designed.

Data storage and management. This includes databases, file storage, data warehouses, caches, and other ways of storing and retrieving information. Requirements related to performance, consistency, scalability, privacy, security, retention, and access will impact how data is structured, stored, managed, and retrieved.

Infrastructure and runtime environment. This includes the cloud services, servers, networks, operating systems, containers, and platforms your system runs on. Requirements related to availability, scalability, performance, security, cost, deployment, and operations can shape the infrastructure and runtime environment you choose.

Fig 9.1 The main logical layers of a system, with security as a cross-cutting requirement that spans every layer.

Some architecture requirements describe qualities your product needs to exhibit, commonly called quality attributes (Bass et al., 2021), such as performance, availability, security, scalability, or maintainability. Others describe constraints the product must operate within, such as required technologies, existing platforms it must integrate with, regulations or standards it must comply with, or limits on cost and infrastructure.

Architecture requirements and their priorities will vary by organization, stakeholders, and the technology already in place, and new requirements may emerge as those conditions change. Your goal is to identify the requirements that could materially affect the architecture, make them specific enough to guide decisions, and understand the trade-offs they create.

The following sections describe common types of architecture requirements so you can identify the areas most likely to shape your product's architecture.

Accessibility

Accessibility requirements define how people must be able to perceive, operate, understand, and interact with the product (World Wide Web Consortium, 2024). They can affect interface components, authentication, document formats, notifications, keyboard operation, and compatibility with assistive technologies. You should identify the organizational, contractual, or regulatory accessibility standards that apply to the product so you can translate these into specific accessibility requirements.

Accuracy

Accuracy requirements describe how close information, calculations, measurements, or other outputs need to be to the expected result. Rather than simply saying that your product needs to be accurate, be specific about how accurate it needs to be, how much error is acceptable, and how you will measure it.

These requirements are particularly important when your product performs calculations or produces values where small errors could have significant consequences, such as in financial, healthcare, scientific, or research systems.

Availability

Availability requirements define when and how consistently your product must be operational and available to its users or other systems. Availability is often expressed as the percentage of time a service must be available during a defined period and may include:

• Uptime percentage: The proportion of time the system must be operational, often expressed in "nines," such as 99.9%, 99.99%, or 99.999%.
• Downtime limits: The maximum amount of scheduled or unscheduled downtime permitted during a defined period, such as a month or year.
• Recovery requirements: How quickly it must be restored after a failure or interruption.

Small differences in availability targets can have a big impact on the complexity and cost of a product's architecture. For example, 99.9% availability allows about 8.8 hours of downtime per year, while 99.99% allows only about 53 minutes. Reaching the higher target may require additional redundancy, automated failover, monitoring, backup infrastructure, and other capabilities to keep the product running when something goes wrong. Each of these adds to the cost and complexity of the architecture needed.

Compliance and governance

Compliance requirements come from obligations such as laws, regulations, contracts, and external standards. Governance requirements come from the policies, rules, and controls an organization uses to manage its information and systems. Both can place important constraints on the architecture of your product.

Common requirements include:

• Data handling. What information is in scope, where it may be stored or processed, how it must be protected, and how it may be used or shared.
• Access control. Who can access particular information or capabilities, what they are allowed to do, and under what conditions.
• Logging. What activities or events must be recorded, what information needs to be captured, who can access those records, and how they must be protected from unauthorized changes.
• Retention and deletion. How long information must be kept and when it must be deleted. Different obligations may specify minimum or maximum retention periods, so these requirements sometimes need to be reconciled.
• Auditability. What evidence the product must capture and retain so the organization can demonstrate that required controls were followed or reconstruct what happened when needed.

These requirements should be identified early because they can affect decisions about data storage, access, system boundaries, integrations, logging, and operational processes. In regulated environments, you will often need to work with legal, compliance, security, or governance specialists to understand which obligations apply and translate them into requirements for the product.

Explainability

Products that use AI, machine learning, or other complex models may need requirements that help people understand, trace, or review the decisions, outputs, or actions they produce. What you need will depend on what the product is doing, how important the decision or action is, and who needs to understand or review it.

Different people may also need different levels of information. For example, a user might need a clear explanation of a particular recommendation, while an auditor or technical team may need to trace an output or action back to the inputs, data, model version, rules, retrieved information, or other factors that contributed to it.

When defining these requirements, consider who needs to understand or review the output, what they need to know, and what information needs to be captured to support those needs. This will affect what the product records, how long that information is retained, and whether someone can later review what happened and understand how a particular decision, output, or action was produced.

Integration and Interoperability

Integration and interoperability requirements describe how your product needs to work with other systems, services, or data sources. This might include exchanging information, requesting a service, responding to an event, or coordinating work across systems.

Integration requirements identify which systems your product needs to connect to and what needs to move between them. Interoperability requirements focus on whether those systems can exchange and use that information correctly. This might depend on shared data definitions, identifiers, formats, standards, or interfaces.

To identify these requirements, look at the environment in which your product will operate and the systems it depends on. Identify which systems need to interact, what information or events need to move between them, in which direction, and when. Also consider any required standards or formats, security and access constraints, and what should happen if another system is unavailable or changes.

These requirements will later help you make decisions about how systems connect and exchange information, how data needs to be translated between them, and how your product should respond when another system fails or changes.

Maintainability

Most systems need to change after launch, whether you are fixing defects, adapting to new needs, updating dependencies, or extending the system over time. Maintainability requirements describe how easily those changes need to be made. Maintainability includes:

• Modifiability and extensibility: How easily existing capabilities can be changed or new ones added without requiring extensive changes elsewhere in the system.
• Testability: How easily components and changes can be tested to determine whether they work as expected.
• Analysability and diagnosability: How easily developers or operations teams can diagnose bugs, trace errors, or identify performance problems, often supported by logging, monitoring, and tracing.
• Modularity: How well the system is divided into independent, loosely coupled components so that changes in one area do not unnecessarily affect others.

Defining these requirements helps ensure that when new feature requests, unexpected bugs, or technology changes occur, the team can respond without introducing unnecessary risk or requiring extensive rework.

Performance

Performance requirements describe how quickly your product needs to respond or complete certain tasks or operations. Be specific about both the performance you need and the scenarios or conditions in which you expect it to be met, such as the number of concurrent users, number of transactions, the amount of data, or a combination of these factors. For example, instead of saying a search should be fast, you might specify that 95% of search requests should complete within two seconds with 500 concurrent users.

The targets you set can have a significant impact on the cost and complexity of your solution, so be sure that whatever targets you set are realistic and based on evidence or reasonable assumptions. For example, a response time of two seconds may be relatively straightforward to meet, while a target of 200 milliseconds may require a more complex design or additional infrastructure.

Performance requirements can affect, and be affected by, other needs such as security, reliability, or consistency, so identify these trade-offs early rather than discovering them during implementation.

Common measures include:

• Response time: How long the product takes to complete a request.
• Throughput: The number of transactions or requests the product can process within a defined period.
• Concurrent users: The number of users the product needs to support at the same time while still meeting its performance targets.
• Resource utilization: Limits on the processor, memory, storage, network, or database resources the product can use under expected load.

Scalability

Performance and scalability are closely related but describe different needs. While performance requirements define how quickly your product needs to respond or process work, scalability requirements describe how much that workload can grow while the product continues to meet those performance targets. That growth might come from more users, transactions, or increased data volumes.

For example, you might define how many concurrent users, transactions per second, or how much data the product should support while still meeting an acceptable response time.

Be realistic and specific about the amount of growth you expect and the assumptions or evidence you used to estimate it. Supporting additional growth will usually have cost and design implications, so avoid specifying more capacity than the product is likely to need. If you expect demand to vary significantly over time, such as during a busy reporting period, capture this as part of the requirement. You may also need to consider elastic, where resources can be added or reduced as demand changes rather than maintaining enough capacity for peak demand all the time.

Meeting these requirements might eventually involve adding resources to existing infrastructure, adding servers or service instances, or using services that scale automatically, which can also introduce different trade-offs in cost, complexity, deployment, and data management.

Fig 9.2 Vertical scaling adds capacity to an existing resource, while horizontal scaling adds more instances behind workload distribution.

Security

Security covers a broad range of concerns, including authentication and authorization, data protection and encryption, logging and monitoring, vulnerability management, auditability, and security testing. Regulations, organizational policies, and risk assessments often drive specific security requirements and controls.

Security requirements should be explored early because they can influence many areas of the architecture as well as operational practices once your product is deployed and in use.

When defining security requirements, you should involve security specialists as they can help you understand any organizational standards and current security practices that you need to meet.

Organizational and technical Constraints

Constraints limit the choices you can make when designing your product. They can come from regulations or contractual obligations, the standards and platforms your organization requires or already uses, the skills available on the team, budget and schedule limits, and commitments already made to customers or partners.

Common examples include having to use a particular cloud provider or platform, follow your organization's security practices, use a specific database that other systems already depend on, or manage and retain records in a particular way.

When you identify a constraint, record where it comes from and how much flexibility, if any, you have in responding to it. Some constraints, such as regulatory or contractual requirements, may leave little room for change but still allow different ways of meeting them. Others, such as preferred technologies or established integration approaches, may allow exceptions or alternatives under certain conditions and with the right approval.

How to Explore and Identify Architecture Needs

Architecture requirements can be easy to miss as they might not be explicitly mentioned by stakeholders, can be expressed vaguely, and they tend to be embedded inside other requirements rather than stated on their own (Chen et al., 2013). Start by reviewing what you already know about the product, its users, the organization, and the environment in which it will operate. Look for requirements that could shape important architecture decisions: how quickly the system needs to respond, when it needs to be available, how much demand it needs to support, what information needs to be protected, what other systems it must work with, and what technical or organizational constraints apply.

This information can come from stakeholder interviews, existing documentation, system diagrams, operational data, regulations and policies, technical research, and discussions with development, security, data, infrastructure, and operations teams.

Managing trade-offs

Meeting a certain architecture requirement might make it harder or more expensive to implement another requirement, or other required functionality.

For example, greater availability may require additional infrastructure and increase operating costs, while additional security controls may affect usability or performance. As you document and prioritize architecture requirements, look for requirements that compete with one another.

The Architecture Tradeoff Analysis Method (ATAM) can be used to evaluate a proposed architecture with stakeholders and identify where quality goals trade off against each other (Kazman et al., 2000). You can use a similar approach as you define and document your architecture requirements:

1. Identify requirements that clash. Look for requirements that impact another, such as a need to encrypt data in a database that might add latency to a critical process.
2. Explore options. Consider what happens if you prioritize one requirement over the other and compare the impact of this prioritization.
3. Evaluate trade-offs using your product's goals. Base your choice on:
   • Business drivers and product strategy: Align the decision with your product's goals and what matters most to your stakeholders.
   • Risk and the cost of failure: Weigh the potential harm of failing one requirement versus another, such as comparing the financial impact and reputational damage of a data breach against a slower process.
   • Reversibility: Determine whether the decision is difficult to undo later or if it's easy to update once your solution is being used.
   • Hard constraints: Factor in any non-negotiable boundaries like fixed budgets, compliance mandates, or your team's capabilities.
4. Decide on a priority or balance. Determine which requirement takes precedence or whether an acceptable compromise can be achieved.
5. Document the decision and remaining risks. Record what you decide, its rationale, and any risks or trade-offs (for example using an architecture decision record) so that later teams understand the context behind your design.

Your goal here is to make important tensions visible and evaluate them so that you and your team can be deliberate about the trade-offs you need to make, rather than discovering them once you start implementation which can result in costly delays and rework.

Architecture Workshops

Architecture workshops can bring stakeholders and technical specialists together to review product goals and known requirements, identify missing needs or constraints, and sketch possible architectures. Making a possible design visible can expose dependencies, assumptions, risks, and trade-offs that were not obvious from the requirements alone.

Prototypes and Technical Spikes

Prototypes can help you explore and refine architecture requirements before committing to a particular design. They might be used to test an integration, try a particular data-processing approach, simulate expected demand, or explore how a component behaves under certain conditions, helping you clarify your requirements, test any assumptions you've made, and identify where you need to make trade-offs.

A technical spike is a short, time-boxed investigation focused on reducing a specific area of technical uncertainty, and may include building a small prototype, running an experiment, or testing a technology in your actual environment. For example, you might use one to uncover the limitations in a third-party API, test whether a performance target is realistic, or understand how your solution behaves when another system is unavailable.

The results give you evidence you can use to refine your requirements and make better architectural decisions, replacing assumptions with something you've actually tested.

Documenting Architecture Requirements and Decisions

The approaches below help you communicate the proposed design and record the requirements and decisions behind it. When defining architecture requirements, make them as specific and verifiable as possible. Where a requirement can be measured, define the target and the conditions under which it must be met. For example, instead of saying "the system must be fast," define the expected response time and the level of demand under which that target must be met.

Use Architecture Diagrams to Illustrate the Design

Architecture diagrams show the overall structure of your product, showing elements such as applications, services, data stores, interfaces, external integrations, and the relationships and communication channels between them.

Architecture diagrams are particularly helpful when exploring requirements related to performance, availability, security and scalability, as drawing the system and its relationships can help you identify dependencies, single points of failure, where access needs to be controlled, integration risks, and potential performance bottlenecks that may be difficult to identify from written requirements alone.

For example, mapping the system might help you identify that every service depends on a single database, creating a single point of failure that wasn't apparent in your written requirements.

Common Elements of an Architecture Diagram

• External Systems and Users. The people, organizations, and outside systems that interact with your product, such as a payment provider or identity service.
• Components. The functional units of the system (e.g., API gateways, authentication service, front-end client, message broker).
• Data Stores. The repositories where data is stored, such as relational databases, NoSQL stores, and file stores.
• Boundaries and Zones. Visual groupings that indicate physical, logical, or security separation (e.g., a Virtual Private Cloud, a secure subnet, or a geographic region).
• Relationships and Data Flows. Connectors showing how components interact with one another, including the flow of data and execution. Labels typically specify protocols and integration approaches.

Capturing Important Architecture Decisions

Architecture Decision Records (ADRs) provide a simple way to record important architecture decisions and explain why they were made, helping you connect decisions back to requirements, constraints, alternatives, and trade-offs you considered, and make assumptions that might otherwise remain hidden more explicit. They also give you something to return to later if the context or requirements change (Keeling, 2022).

The format can vary, but an ADR will usually describe the context for the decision, the options considered, the decision you made, and the consequences that follow. Keep each ADR short and focused on one important decision.

Example ADR

ADR 004: Use a managed relational database service

Status: Accepted

Context: The system must support transactional updates, encrypted storage, daily backups, and high availability for internal operations. The team has limited capacity to manage database infrastructure directly, and downtime during business hours would disrupt critical work.

Decision: Use a managed PostgreSQL service rather than self-hosting the database on virtual machines.

Alternatives considered:

• Self-host PostgreSQL on cloud infrastructure. Rejected because the team does not have the capacity to manage patching, backups, replication, and failover.
• Use a NoSQL document database. Rejected because the system needs consistent transactional updates and structured relationships between its data, which fit a relational model more closely.

Consequences: A managed service handles backups, patching, replication, and failover, reducing the operational load on the team. The trade-off is a higher recurring platform cost and less control over low-level configuration. If performance or scaling needs change significantly, this decision may need to be revisited.

Backlog Items and Acceptance Criteria

Representing architecture needs and its related work in the backlog helps ensure it is prioritized, estimated, and tracked through the same process as other development work, improving visibility and giving you a more complete picture of the work needed to deliver your product.

There are several ways you can capture this work in the backlog, including:

• Epics are useful when an architecture requirement involves multiple pieces of work that may span several iterations, such as improving platform security, implementing audit logging across the product, or increasing system resilience.
• User stories are useful when there is a clear capability that a user or stakeholder needs and architecture requirements affect how that capability needs to work. For example, an administrator may need to review audit logs or a customer may need to upload a document. Requirements related to things such as performance, security, or availability can then be captured in the story's acceptance criteria. However, not every architecture requirement needs to be forced into a user-story format. Technical or architecture work that does not directly relate to a user interaction is often clearer as a technical backlog item.
• Acceptance criteria are an effective way to capture architecture-related needs that apply to a particular backlog item and provide a way to test whether those needs have been met. For example, a document upload story might include the criterion: "Uploads complete within 3 seconds for files up to 25 MB."

Using These Artifacts Together

These approaches complement each other because they help you describe different aspects of the same architecture requirement. For example, suppose your product requires uploaded files to be encrypted when they are stored. You could use:

• An architecture diagram to show where uploaded files move through the system, where they are stored, and which components are responsible for handling them.
• An ADR to record the decision to use a managed storage service that provides encryption at rest, along with the alternatives considered, the reasoning behind the choice, and its trade-offs.
• Backlog items to capture the work needed to implement and verify the requirement, including acceptance criteria that can be prioritized and completed during an iteration.

Together, these artifacts give you a more complete picture, as the diagram shows how the system is structured, the ADR explains why an important design decision was made, and the backlog helps translate the requirement into work that can be planned, implemented, and tested.

References