2. Requirements, Quality Attributes and Architecture Documentation

Introduction: From Business Intent to Architectural Direction

Software architecture is not produced by selecting a fashionable framework or by arranging components into layers. It is a reasoned response to a problem faced by an organisation, its users, and its technical teams. The quality of that response depends first on how well the problem is understood. Requirements therefore provide the foundation for architecture, but not all requirements influence architecture in the same way.

A requirement such as “the system shall allow a customer to update an address” is important for functionality, yet it may have limited architectural significance. By contrast, “the system shall support 50,000 concurrent users while maintaining a response time below two seconds” directly affects deployment, data management, communication protocols, caching, scalability, and monitoring. Requirements that significantly shape architectural decisions are known as architectural drivers.

This chapter explains how business goals, functional requirements, constraints, and quality attributes are translated into architectural drivers. It then presents practical techniques for expressing quality attribute scenarios, prioritising concerns through utility trees, analysing trade-offs, documenting architecture through C4 and 4+1 views and UML, and recording decisions, risks, and proof-of-concept results. These practices are especially important in full stack development, where the architecture must coordinate user interfaces, APIs, business services, data stores, infrastructure, security controls, and operational processes.

Learning Objectives

After studying this chapter, students should be able to:

1. Distinguish business requirements, functional requirements, constraints, and quality attributes.

2. Identify and prioritise architectural drivers.

3. Construct quality attribute scenarios and utility trees.

4. Analyse architectural trade-offs using explicit reasoning.

5. Document architecture using C4, 4+1, and appropriate UML diagrams.

6. Prepare architecture decision records, risk registers, and proof-of-concept evaluation plans.

7. Apply these techniques to a realistic full stack application.

8. Recognise governance, ethical, security, and professional responsibilities in architecture work.

Requirements as Inputs to Architecture

Requirements describe desired capabilities, behaviours, restrictions, and outcomes. They are not merely a list of features for developers to implement. In architecture work, requirements are interpreted in relation to uncertainty, cost, risk, organisational strategy, and system evolution.

Business goals and stakeholder concerns

Business goals express why an organisation is investing in a system. Examples include reducing order-processing costs, entering a new market, improving customer retention, complying with regulation, or enabling a new revenue model. Stakeholder concerns are the interests that different groups want the architecture to protect. Customers may value availability and privacy; operations teams may value observability and recoverability; finance teams may value cost control; developers may value maintainability and testability.

A business goal becomes architecturally meaningful when it is translated into measurable or observable system consequences. For example, “expand into international markets” may imply multilingual interfaces, regional data residency, time-zone support, currency conversion, resilience across regions, and compliance with local laws. The goal itself is strategic, while these consequences become architectural concerns.

Functional requirements

Functional requirements specify what the system does. They describe services, workflows, calculations, interactions, and business rules. In a full stack application, functional requirements may include registration, authentication, product search, payment processing, reporting, notifications, or administrative configuration.

Functional requirements influence architecture when they involve complex domain rules, high transaction volumes, integration with external systems, strong consistency, or independent rates of change. A simple reporting function may remain within an existing service, whereas a complex pricing engine may deserve a separate bounded context or service boundary.

Quality attribute requirements

Quality attributes describe how well a system performs its functions. Common attributes include:

• Performance: response time, throughput, latency, and resource efficiency.
• Availability: the proportion of time a system is operational and usable.
• Reliability: the ability to perform correctly over a period under stated conditions.
• Scalability: the ability to handle increased workload through additional resources or design changes.
• Security: protection of confidentiality, integrity, authentication, authorisation, and accountability.
• Modifiability: the effort required to change the system safely.
• Usability and accessibility: the ease and inclusiveness with which users accomplish tasks.
• Testability: the ease of verifying system behaviour.
• Deployability: the ability to release changes safely and efficiently.
• Observability: the ability to infer internal system conditions from outputs such as logs, metrics, and traces.

Quality attributes are often more influential than individual features because they constrain the structure of the solution. For example, a requirement for rapid independent releases may encourage modular boundaries, automated testing, continuous delivery, and backward-compatible APIs.

Constraints and assumptions

Constraints are restrictions on the solution space. They may arise from legislation, organisational policy, existing infrastructure, budget, technology standards, skills, contracts, or deadlines. “The application must use the organisation’s identity provider” is a constraint. “The first release must be delivered within four months” is a schedule constraint. Constraints should not be confused with preferences. A preference can be reconsidered; a genuine constraint normally cannot be ignored without formal approval.

Assumptions are beliefs accepted temporarily because complete information is unavailable. Examples include an expected traffic profile, the availability of a third-party API, or the anticipated growth of a user base. Every significant assumption should have an owner and, where possible, a validation plan. Unchecked assumptions are a common source of architectural failure.

Architectural Drivers and Their Prioritisation

An architectural driver is a requirement, constraint, risk, or business concern that materially affects the architecture. Drivers answer the question: which facts must the architect take seriously when choosing among possible structures?

A useful driver statement identifies the stakeholder, concern, context, and consequence. For example: “During peak enrolment, students should receive a course-search response within two seconds at the 95th percentile for 10,000 concurrent users.” This is stronger than “the search must be fast” because it provides a basis for design and testing.

Drivers are prioritised because resources are limited and quality attributes frequently conflict. Security, performance, cost, and speed of delivery cannot always be maximised simultaneously. Prioritisation may consider business value, technical risk, regulatory exposure, urgency, and cost of delay. A practical classification is:

• Must satisfy: failure is unacceptable or legally impermissible.
• Should satisfy: important, but limited compromise may be possible.
• Could satisfy: desirable if resources permit.
• Deferred: consciously excluded from the current release.

A prioritisation workshop should involve business representatives, product owners, developers, operations personnel, security specialists, and relevant users. Architects should avoid treating prioritisation as a purely technical activity because the relative importance of attributes is a business decision.

Quality Attribute Scenarios

Quality attribute scenarios convert vague quality concerns into testable statements. A scenario generally contains six elements:

1. Source: the person, system, event, or condition generating the stimulus.

2. Stimulus: the event that affects the system.

3. Environment: the operating condition in which the stimulus occurs.

4. Artifact: the system or component affected.

5. Response: the behaviour expected from the system.

6. Response measure: the criterion used to judge success.

For example:

“An unauthenticated user submits a product-search request during normal operation. The search service returns the first page of results within two seconds for at least 95 percent of requests.”

This scenario identifies the source, stimulus, environment, artifact, response, and measure. It can guide architectural decisions about indexing, caching, pagination, API design, and performance testing.

A security scenario might state: “When a user attempts to access an administrative endpoint without the required role, the API rejects the request, records an audit event, and exposes no protected data.” A modifiability scenario might state: “When a new payment provider is introduced, a developer can add the provider without changing order-management rules, with regression tests completed within one working week.”

Scenarios should be realistic, measurable, and connected to stakeholder value. Vague terms such as “highly secure” or “easy to maintain” should be replaced with observable behaviour and thresholds.

Utility Trees and Architectural Priorities

A utility tree is a structured method for exploring and prioritising quality attributes. The root is overall system utility. Major branches represent quality attributes, such as performance, security, availability, and modifiability. Lower branches represent more specific concerns, and leaves represent quality attribute scenarios.

Each scenario is commonly evaluated using two dimensions: importance to stakeholders and difficulty or risk of achieving it. A scenario with high importance and high technical difficulty becomes a major architectural driver. A low-importance, low-difficulty scenario is less likely to shape the architecture.

For example, an online examination platform might prioritise:

• Availability during scheduled examinations: high importance, high difficulty.
• Protection against unauthorised access to examination content: high importance, high difficulty.
• Response time for submitting an answer: high importance, medium difficulty.
• Support for a new colour theme: low importance, low difficulty.

The utility tree does not mechanically select an architecture. Its purpose is to make priorities visible and expose disagreements. If business stakeholders rank availability highest while operations teams identify recoverability as the greatest technical risk, the difference should be discussed rather than hidden.

Architectural Trade-Off Analysis

Architecture is an exercise in trade-offs. Improving one quality attribute can weaken another. Strong encryption may increase processing overhead; extensive redundancy may increase cost; highly decoupled services may improve independent deployment but add operational complexity; aggressive caching may improve performance while creating data-staleness risks.

Trade-off analysis should be explicit. A disciplined process includes:

1. Identify the decision and the alternatives.

2. Relate each alternative to the relevant quality scenarios.

3. Identify architectural mechanisms used by each alternative.

4. Estimate benefits, costs, risks, and operational consequences.

5. Determine sensitivities: which assumptions could change the decision?

6. Record the decision and define validation activities.

Suppose a product catalogue can use a relational database with indexed queries or a search engine. The relational option may offer transactional simplicity and fewer operational components. A search engine may provide richer text search and faster retrieval at scale, but introduces data-synchronisation and operational concerns. The correct decision depends on actual scenarios, not on the general reputation of either technology.

Trade-off analysis should distinguish between a trade-off and a non-negotiable constraint. If legislation requires encryption of personal data, encryption is not simply an optional alternative to lower cost. The design must meet the requirement, while trade-offs may concern algorithm choice, key management, performance, and operational procedure.

Documenting Architecture Through Multiple Views

Architecture documentation serves several audiences. Executives need a concise explanation of scope, risks, and investment. Developers need responsibilities, interfaces, dependencies, and constraints. Testers need behaviour and acceptance conditions. Operations teams need deployment topology, monitoring, recovery, and security information. No single diagram can communicate all of this effectively.

The C4 model

The C4 model provides a hierarchical way to describe software architecture:

• System context: the system, its users, and external systems.
• Container: independently deployable or significant runtime units, such as a web application, API, database, or message broker.
• Component: major building blocks inside a container.
• Code: implementation-level structures, such as classes or modules.

The term container in C4 does not necessarily mean a Docker container. It refers to a boundary in which code executes or is stored. C4 diagrams are useful because readers can move from a broad context to an appropriate level of detail without being overwhelmed by implementation information.

A system-context diagram for a learning platform may show students, instructors, an identity provider, a payment service, and the learning platform. A container diagram may then show a browser application, API, relational database, object storage, notification adapter, and reporting service. A component diagram for the API may show enrolment, catalogue, identity, and payment components.

The 4+1 view model

The 4+1 model describes architecture through five complementary views:

• Logical view: key abstractions, responsibilities, and relationships.
• Development view: modules, packages, components, and ownership from the developer perspective.
• Process view: runtime processes, communication, concurrency, and synchronisation.
• Physical view: deployment nodes, infrastructure, networks, and allocation of software to hardware or cloud resources.
• Scenarios: use cases that demonstrate and validate the other views.

The views are not competing diagram styles. They are perspectives for different questions. The logical view asks what responsibilities exist. The process view asks how runtime interactions occur. The physical view asks where software runs. The development view asks how the codebase is organised. Scenarios connect the views to actual system behaviour.

UML in architectural communication

UML remains useful when applied selectively. Use-case diagrams clarify actors and system goals. Sequence diagrams show time-ordered interactions. Class or domain diagrams express important concepts and relationships. Activity diagrams describe workflows. State-machine diagrams are appropriate when an entity changes through meaningful states, such as an order moving from pending to paid, dispatched, delivered, or cancelled. Deployment diagrams show nodes and communication paths.

A diagram should answer a specific question. Excessive notation, unexplained symbols, and diagrams that are never updated reduce trust. Each diagram should have a title, scope, legend where necessary, and a short explanatory narrative.

Architecture Decision Records

An Architecture Decision Record (ADR) captures a significant decision in a concise, durable form. A typical ADR contains:

• Title and decision identifier.
• Status, such as proposed, accepted, superseded, or rejected.
• Context and problem statement.
• Decision and chosen approach.
• Alternatives considered.
• Consequences, including benefits and liabilities.
• Validation evidence or follow-up actions.

For example, an ADR might record the decision to use asynchronous messaging for email notifications. The context could state that user-facing requests should not wait for a third-party email provider. The consequences might include improved response time and greater resilience, alongside eventual delivery and the need for retry and dead-letter handling.

ADRs prevent important reasoning from disappearing into meetings or private conversations. They also make future change more rational: a later team can understand not only what was selected but why it was appropriate under the conditions existing at the time. ADRs should record meaningful decisions, not every minor implementation choice.

Risk Registers and Proofs of Concept

A risk register records uncertainty that could harm delivery, operation, compliance, or business value. Useful fields include risk description, cause, consequence, probability, impact, exposure, owner, mitigation, contingency, trigger, and status.

A risk is different from an issue. A risk may occur; an issue has already occurred. “The selected payment provider may not support required settlement rules” is a risk. “The provider rejected the settlement request” is an issue. Confusing the two leads to weak management responses.

A proof of concept (PoC) is a focused experiment designed to reduce uncertainty. It should not be mistaken for a production-ready prototype. A good PoC begins with a hypothesis, defines measurable success criteria, limits scope, identifies test data, and specifies a timebox. For example, a team considering event streaming might test whether the proposed broker can handle the required event rate, preserve ordering where necessary, recover after consumer failure, and provide adequate operational visibility.

PoC evaluation should include technical results and decision implications. “The technology worked” is insufficient. The team should ask: under what load, with what configuration, at what cost, and with what operational burden? Negative results are valuable when they prevent an expensive commitment.

Applied Case: A University Course Registration Platform

Background

The following is an illustrative case. A university intends to replace a fragmented course-registration platform. Students must browse courses, check prerequisites, register, withdraw, and receive confirmation. Faculty members manage capacity and schedules. The platform must integrate with the identity service, student records system, payment service, and notification provider.

Situation and problem

The existing platform performs adequately in ordinary periods but becomes unavailable during registration windows. Students submit duplicate requests because the interface provides little feedback. Faculty staff cannot reliably see current capacity. The university also faces privacy obligations concerning student information and requires an audit trail for registration changes.

Architectural analysis

The major business goals are to reduce registration failure, improve student experience, and provide reliable capacity information. Architectural drivers include:

• During peak registration, 95 percent of course-search requests should complete within two seconds.
• Registration decisions must prevent capacity from being exceeded.
• A confirmed registration must be traceable through an audit record.
• A failure in the notification provider must not lose a successful registration.
• Personal data must be protected through authenticated and authorised access.
• A new notification provider should be introducible without changing registration rules.

The utility tree identifies peak availability, transactional correctness, security, and modifiability as high-priority concerns. The team recognises a trade-off between strict synchronous integration with every external system and a more resilient architecture using local data and asynchronous updates.

Approach and solution

The proposed architecture separates the browser application from an API layer. Registration is managed by a domain component that enforces prerequisites, capacity, and duplicate-submission protection. A relational database provides transactional consistency for registration decisions. Course-search data is indexed and cached because search traffic is high and can tolerate brief propagation delay, while registration commands use authoritative transactional data.

After a successful registration transaction, an event is placed in a durable outbox. A background publisher sends the event to a notification component, which retries failed deliveries and records messages that require manual review. This prevents the notification provider from determining whether the registration itself succeeds.

The identity provider authenticates users, while application-level authorisation determines whether the user is a student, faculty member, or administrator. Audit records are protected from ordinary modification and include the actor, action, time, and relevant registration identifier.

An ADR records the choice of a relational database for registration transactions and an indexed read model for course search. Another ADR records the outbox pattern for reliable notification. The risk register includes external identity-provider outages, inaccurate enrolment data, peak-load saturation, and privacy breaches. A PoC tests peak search load, concurrent registration for the final available seat, recovery of a failed notification consumer, and audit completeness.

Outcome

The resulting design does not attempt to make every operation synchronous or equally consistent. It gives strong consistency to the business decision that requires it, while allowing search and notification processes to use mechanisms suited to their own quality scenarios. The documentation enables separate conversations with academic administrators, developers, security reviewers, and operations staff.

Learning points

The case demonstrates that architecture emerges from prioritised requirements rather than from technology selection alone. It also shows why quality attribute scenarios, decision records, risk management, and targeted experiments should be connected. Each artefact supports a different form of reasoning, but together they create an evidence-based architectural narrative.

Common Failure Modes and Professional Responsibilities

A frequent mistake is beginning with a solution—such as microservices, serverless computing, or a particular cloud platform—before identifying the drivers. Technology may later be selected, but it should respond to a problem. Another mistake is documenting only the intended structure and omitting operational behaviour, failure modes, security boundaries, or data ownership.

Unmeasurable quality requirements create disputes late in delivery. “The application must be scalable” does not specify workload, growth, response criteria, or scaling time. Similarly, a diagram with no owner becomes obsolete. Architecture documentation must be treated as a maintained product, with review points connected to major changes.

Architects also face ethical and governance responsibilities. They must avoid concealing known risks, overstating PoC results, or presenting assumptions as facts. Privacy should be considered through data minimisation, purpose limitation, access control, retention, and appropriate protection of sensitive information. Security decisions should account for least privilege, auditability, secure defaults, threat modelling, and responsible handling of vulnerabilities. Accessibility should not be treated as an optional enhancement when users with disabilities depend on the system.

AI-assisted development introduces further architectural concerns. Generated code may contain security defects, licence complications, undocumented dependencies, or inappropriate data handling. Teams should define review responsibilities, protect confidential prompts and training data, and validate generated components against requirements and quality scenarios. Automation is valuable, but it does not transfer accountability away from professionals.

Emerging Practice

Architecture documentation is increasingly supported by lightweight, version-controlled approaches. “Docs as code” places diagrams, ADRs, interface descriptions, and operational guidance alongside source code, enabling peer review and change history. Model-based tools can generate diagrams from structured descriptions, although generated views still require human interpretation.

Observability is becoming an architectural driver rather than an operational afterthought. Distributed tracing, structured logging, service-level indicators, and error budgets help teams evaluate whether runtime behaviour satisfies quality scenarios. Platform engineering also encourages reusable deployment, security, and monitoring capabilities, allowing product teams to focus on domain value while retaining governance.

Event-driven architecture, edge execution, managed cloud services, and AI-enabled features create new possibilities, but each introduces assumptions and risks. Contemporary architecture practice therefore requires continuous validation. The most valuable documentation is not the most elaborate; it is documentation that supports sound decisions, exposes uncertainty, and remains useful when the system changes.

Best Practices for Architecture Work

1. Begin with business outcomes and stakeholder concerns, not preferred technologies.

2. Convert important quality concerns into measurable scenarios.

3. Separate requirements, constraints, assumptions, risks, and decisions.

4. Prioritise drivers explicitly and involve non-technical stakeholders.

5. Use the least complex architecture that satisfies the important scenarios.

6. Select diagrams according to audience and question.

7. Record significant decisions and their consequences in ADRs.

8. Use PoCs to test uncertainty, not to create disguised production systems.

9. Link risks and scenarios to tests, monitoring, and operational procedures.

10. Review architecture documentation whenever drivers, boundaries, or major dependencies change.

Chapter Summary

Architecture translates business intent into a structure capable of delivering useful and dependable software. Functional requirements describe system capabilities, while quality attributes, constraints, assumptions, and risks determine how those capabilities must be realised. Requirements with substantial structural influence become architectural drivers.

Quality attribute scenarios make concerns measurable by identifying a source, stimulus, environment, artifact, response, and response measure. Utility trees help prioritise scenarios according to stakeholder importance and technical difficulty. Trade-off analysis makes the costs and consequences of alternative designs visible.

The C4 model provides nested levels of architectural communication, while the 4+1 model offers logical, development, process, physical, and scenario perspectives. UML diagrams should be selected according to the question they answer. ADRs preserve architectural reasoning; risk registers organise uncertainty; and PoCs provide focused evidence before significant commitment. Effective architecture documentation is concise, audience-aware, maintained, and connected to testing, governance, security, and operations.

Key Terms

Architectural driver: A requirement, constraint, risk, or concern that significantly influences architecture.

Business goal: An organisational outcome that motivates investment in a system.

Functional requirement: A specification of a capability or behaviour the system must provide.

Quality attribute: A characteristic describing how well a system performs its functions.

Constraint: A restriction that limits available architectural choices.

Assumption: A condition accepted provisionally because it has not yet been fully verified.

Quality attribute scenario: A measurable statement describing a stimulus and the required system response.

Utility tree: A hierarchical model used to prioritise quality attributes and scenarios.

Trade-off: A design situation in which improving one concern affects another concern.

C4 model: A hierarchical architecture documentation approach covering context, containers, components, and code.

Container: A significant runtime or deployment boundary in the C4 model.

4+1 view model: An architecture model comprising logical, development, process, physical, and scenario views.

UML: A standard visual language for modelling software structure and behaviour.

Architecture Decision Record: A concise record of an important architectural decision and its consequences.

Risk register: A managed list of risks, their exposure, owners, and responses.

Proof of concept: A time-bounded experiment intended to reduce technical or architectural uncertainty.

Observability: The ability to understand internal system behaviour from externally produced telemetry.

Architectural scenario: A concrete situation used to assess whether a design satisfies a quality concern.

Outbox pattern: A technique that stores an event with a transaction before reliably publishing it asynchronously.

Review Questions

Short Answer Questions

1. What makes a requirement an architectural driver?

2. Distinguish a quality attribute from a functional requirement.

3. List the six elements of a quality attribute scenario.

4. What is the purpose of an Architecture Decision Record?

5. How does a proof of concept differ from a production prototype?

Long Answer Questions

1. Explain how business goals can be translated into architectural drivers, using a full stack application example.

2. Describe the purpose and construction of a utility tree. How does it support prioritisation?

3. Explain the C4 model and discuss how its levels support different audiences.

4. Compare the logical, process, and physical views in the 4+1 model.

5. Discuss how trade-off analysis, risk registers, and ADRs support responsible architecture governance.

Analytical / Application Questions

1. An online retail application must support rapid product search, accurate payment processing, and low operating cost. Construct three quality attribute scenarios and identify one likely trade-off.

2. A team proposes microservices because the application is expected to grow. What additional evidence and architectural drivers should be examined before accepting the proposal?

3. A notification provider frequently fails after successful transactions. Recommend an architectural approach, identify its consequences, and specify a PoC that could validate it.

22. Multiple Choice Questions with Answers

Question 1

Which statement best describes an architectural driver?

A. Any user interface colour selected by the product team

B. A requirement or concern that materially influences system structure

C. A coding convention used by one development team

D. A completed test case with no architectural consequence

Correct Answer: B. A requirement or concern that materially influences system structure

Question 2

Which quality attribute scenario element specifies the measurable success criterion?

A. Source

B. Environment

C. Response measure

D. Artifact

Correct Answer: C. Response measure

Question 3

In a utility tree, a scenario with high stakeholder importance and high technical difficulty should generally be treated as what?

A. A major architectural driver

B. A deferred cosmetic feature

C. An implementation detail

D. An irrelevant assumption

Correct Answer: A. A major architectural driver

Question 4

Which C4 level shows users and external systems interacting with the system under discussion?

A. Code level

B. Component level

C. Container level

D. System-context level

Correct Answer: D. System-context level

Question 5

Which 4+1 view focuses most directly on runtime communication, concurrency, and synchronisation?

A. Logical view

B. Process view

C. Development view

D. Physical view

Correct Answer: B. Process view

Question 6

What is the principal purpose of an Architecture Decision Record?

A. To replace all automated tests

B. To document significant decisions, alternatives, and consequences

C. To list every line of source code

D. To guarantee that a technology will never change

Correct Answer: B. To document significant decisions, alternatives, and consequences

Question 7

In the course-registration case, why is an outbox pattern appropriate for notifications?

A. It ensures notification delivery determines registration success

B. It stores an event reliably before asynchronous publication

C. It eliminates the need for transaction processing

D. It makes all external systems strongly consistent

Correct Answer: B. It stores an event reliably before asynchronous publication

Question 8

Which statement correctly distinguishes a risk from an issue?

A. A risk is possible; an issue has already occurred

B. A risk is always technical; an issue is always financial

C. A risk needs no owner; an issue always needs one

D. A risk is documented only after failure

Correct Answer: A. A risk is possible; an issue has already occurred

Question 9

What is the most appropriate purpose of a proof of concept?

A. To bypass architectural review

B. To build an unmaintained version of the complete product

C. To reduce a specific uncertainty using measurable criteria

D. To prove that the most familiar technology is correct

Correct Answer: C. To reduce a specific uncertainty using measurable criteria

Question 10

Which is the strongest quality requirement for a search function?

A. The search should be excellent

B. The search should feel modern

C. The search should be fast enough

D. At least 95 percent of searches should return within two seconds under the stated peak workload

Correct Answer: D. At least 95 percent of searches should return within two seconds under the stated peak workload