Requirements define the problem space. They capture what the system must do and what the user actually needs to achieve. We care about them for several key reasons:

• Defining “Correctness”: A requirement establishes the exact criteria for whether an implementation is successful. Without clear requirements, developers have no objective way to know when a feature is “done” or if it actually works as intended.
• Building the Right System: You can write perfectly clean, highly optimized, bug-free code—but if it doesn’t solve the user’s actual problem, the software is useless. Requirements ensure the engineering team’s efforts are aligned with user value.
• Traceability and Testing: Good requirements allow developers to write clear acceptance criteria and enable traceability – the ability to link implemented features back to the requirements that motivated them. This supports impact analysis when requirements change and helps verify that the system delivers what was requested.

Requirements vs. Design

In software engineering, distinguishing between requirements and design is critical to building successful systems. Requirements express what the system should do and capture the user’s needs. The goal of requirements, in general, is to capture the exact set of criteria that determine if an implementation is “correct”.

A design, on the other hand, describes how the system implements these user needs. Design is about exploring the space of possible solutions to fulfill the requirements. A well-crafted requirements specification should never artificially limit this space by prematurely making design decisions. For example, a requirement for pathfinding might be: “The program should find the shortest path between A and B”. If you were to specify that “The program should implement Dijkstra’s shortest path algorithm”, you would over-constrain the system and dictate a design choice before development even begins.

Examples

Here are some examples illustrating the difference between a requirement (what the system must do to satisfy the user’s needs) and a design decision (how the engineers choose to implement a solution to fulfill that requirement):

• Route Planning
  • Requirement: The system must calculate and display the shortest route between a user’s current location and their destination.
  • Design Decision: Implement Dijkstra’s algorithm (or A* search) to calculate the path, representing the map as a weighted graph.
• User Authentication
  • Requirement: The system must ensure that only registered and verified users can access the financial dashboard.
  • Design Decision: Use OAuth 2.0 for third-party login and issue JSON Web Tokens (JWT) to manage user sessions.
• Data Persistence
  • Requirement: The application must save a user’s shopping cart items so they are not lost if the user accidentally closes their browser.
  • Design Decision: Store the active shopping cart data temporarily in a Redis in-memory data store for fast retrieval, rather than saving it to the main relational database.
• Sorting Information
  • Requirement: The system must display the list of available university courses ordered alphabetically by their course name.
  • Design Decision: Use the built-in TimSort algorithm in Python to sort the array of course objects before sending the data to the frontend.
• Cross-Platform Accessibility
  • Requirement: The web interface must be fully readable and navigable on both large desktop monitors and small mobile phone screens.
  • Design Decision: Build the user interface using React.js and apply Tailwind CSS to create a responsive, mobile-first grid layout.
• Search Functionality
  • Requirement: Users must be able to search for specific books in the catalog using keywords, titles, or author names, even if they make minor typos.
  • Design Decision: Integrate Elasticsearch to index the book catalog and utilize its fuzzy matching capabilities to handle user typos.
• System Communication
  • Requirement: When a customer places an order, the inventory system must be notified to reduce the stock count of the purchased items.
  • Design Decision: Implement an event-driven architecture using an Apache Kafka message broker to publish an “OrderPlaced” event that the inventory service listens for.
• Password Security
  • Requirement: The system must securely store user passwords so that even if the database is compromised, the original passwords cannot be easily read.
  • Design Decision: Hash all passwords using the bcrypt algorithm with a work factor (salt) of 12 before saving them to the database.
• Real-Time Collaboration
  • Requirement: Multiple users must be able to view and edit the same code file simultaneously, seeing each other’s changes in real-time without refreshing the page.
  • Design Decision: Establish a persistent two-way connection between the clients and the server using WebSockets, and use Operational Transformation (OT) to resolve edit conflicts.
• Offline Capabilities
  • Requirement: The mobile app must allow users to read previously opened news articles even when they lose internet connection (e.g., when entering a subway).
  • Design Decision: Cache the text and images of recently opened articles locally on the device using an SQLite database embedded in the mobile application.

Why Does the Difference Matter?

Blurring the lines between requirements and design is a common mistake that leads to misunderstandings. In practice, the two are often pursued cooperatively and contemporaneously, yet the distinction matters for three main reasons:

Avoiding Premature Constraints: When you put design decisions into your requirements, you artificially limit the space of possible solutions before development even begins. If a product manager writes a requirement that says, “The system must use an SQL database to store user profiles”, they have made a design decision. A NoSQL database or an in-memory cache might have been vastly superior for this specific use case, but the engineers are now blocked from exploring those better options.

Preserving Flexibility and Agility: Design decisions change frequently. A team might start by using one sorting algorithm or database architecture, realize it doesn’t scale well, and swap it out for another. If the requirement was strictly about the “what” (e.g., “Data must be sorted alphabetically”), the requirement stays the same even when the design changes. This iterative process of swinging between requirements and design helps manage the complexity of what Rittel and Webber termed “wicked” problems (Rittel and Webber 1973) – problems where understanding the requirements depends on exploring the solution. If the design was baked into the requirement, you now have to rewrite your requirements and change your acceptance criteria just to fix a technical issue.

Utilizing the Right Expertise: Requirements are typically driven by the customer or product manager / product owner — the people who understand the business needs. Design decisions are typically led by the software engineers and architects — the people who understand the technology. However, effective teams involve users in design validation (through prototyping and user testing) and engineers in requirements discovery (since technical possibilities shape what can be offered). Mixing the two without clear awareness often results in non-technical stakeholders dictating technical implementations, which rarely ends well.

In short: Requirements keep you focused on delivering value to the user. Leaving design out of your requirements empowers your engineers to deliver that value in the most efficient and technically sound way possible.

Requirements Specifications

User Stories

Quality Attribute Scenarios

Quality attribute requirements (such as performance, security, and availability) are often best captured via “Quality Attribute Scenarios” to make them concrete and measurable (Bass et al. 2012).

Formal Requirements Specifications

Requirements Elicitation

User stories are the most commonly used format to specify requirements in a light-weight, informal way (particularly in projects following Agile processes). Each user story is a high-level description of a software feature written from the perspective of the end-user.

User stories act as placeholders for a conversation between the technical team and the “business” side to ensure both parties understand the why and what of a feature.

Format

User stories follow this format:

As a [user role],

I want [to perform an action]

so that [I can achieve a goal]

For example:

(Smart Grocery Application): As a home cook, I want to swap out ingredients in a recipe so that I can accommodate my dietary restrictions and utilize what I already have in my kitchen.

(Travel Itinerary Planner): As a frequent traveler, I want to discover unique, locally hosted activities so that I can experience the authentic culture of my destination rather than just the standard tourist traps.

This structure helps the team identify not just the “what”, but also the “who” and — most importantly — the “why”.

The main requirement of the user story is captured in the I want part. The so that part primarily clarifies the goal the user wants to achieve. While it should not prescribe implementation details, it may implicitly introduce quality constraints or dependencies that shape the acceptance criteria.

Be specific about the actor. Avoid generic labels like “user” in the As a clause. Instead, name the specific role that benefits from the feature (e.g., “job seeker”, “hiring manager”, “store owner”). A precise actor clarifies who needs the feature and why, helps the team understand the context, and prevents stories from becoming vague catch-alls. If you find yourself writing “As a user”, ask: which user?

Acceptance Criteria

While the story itself is informal, we make it actionable using Acceptance Criteria. They define the boundaries of the feature and act as a checklist to determine if a story is “done”. Acceptance criteria define the scope of a user story.

They follow this format:

Given [pre-condition / initial state]

When [action]

Then [post-condition / outcome]

For example:

(Smart Grocery Application): As a home cook, I want to swap out ingredients in a recipe so that I can accommodate my dietary restrictions and utilize what I already have in my kitchen.

• Given the user is viewing a recipe’s ingredient list, when they select a specific ingredient, then a list of viable alternatives should be suggested.
• Given the user selects a substitute from the alternatives list, when they confirm the swap, then the recipe’s required quantities and nutritional estimates should recalculate and update on the screen.
• Given the user has modified a recipe with substitutions, when they save it to their cookbook, then the customized version of the recipe should be stored in their personal profile without altering the original public recipe.

These acceptance criteria add clarity to the user story by defining the specific conditions under which the feature should work as expected. They also help to identify potential edge cases and constraints that need to be considered during development. The acceptance criteria define the scope of conditions that check whether an implementation is “correct” and meets the user’s needs. So naturally, acceptance criteria must be specific enough to be testable but should not be overly prescriptive about the implementation details, not to constrain the developers more than really needed to describe the true user need.

Here is another example:

(Travel Itinerary Planner): As a frequent traveler, I want to discover unique, locally hosted activities so that I can experience the authentic culture of my destination rather than just the standard tourist traps.

• Given the user has set their upcoming trip destination to a city, when they browse local experiences, then they should see a list of activities hosted by verified local residents.
• Given the user is browsing the experiences list, when they filter by a maximum budget of $50, then only activities within that price range should be shown.
• Given the user selects a specific local experience, when they check availability, then open booking slots for their specific travel dates should be displayed.

INVEST

To evaluate if a user story is well-written, we apply the INVEST criteria:

• Independent: Stories should not depend on each other so they can be implemented and released in any order.
• Negotiable: They capture the essence of a need without dictating specific design decisions (like which database to use).
• Valuable: The feature must deliver actual benefit to the user, not just the developer.
• Estimable: The scope must be clear enough for developers to predict the effort required.
• Small: A story should be small enough that the team can complete it within a single iteration and estimate it with reasonable confidence.
• Testable: It must be verifiable through its acceptance criteria.

Important: The application of the INVEST criteria is often content-dependent. For example, a story that is quite large to implement but cannot be effectively split into separate user stories can still be considered “small enough” while a user story that is objectively faster and easier to implement can be considered “not small” if splitting it up into separate user stories that are still valuable and independent is more elegant. Or a user story that is “independent” in one set of user stories (because all its dependencies have already been implemented) is “not independent” if it is in a set of user stories where its dependencies have not been implemented yet and therefore a dependency is still in the user story set. Understanding this crucial aspect of the INVEST criteria is key to evaluating user stories.

We will now look at these criteria in more detail below.

Independent

An independent story does not overlap with or depend on other stories—it can be scheduled and implemented in any order.

What it is and Why it Matters The “Independent” criterion states that user stories should not overlap in concept and should be schedulable and implementable in any order (Wake 2003). An independent story can be understood, tracked, implemented, and tested on its own, without requiring other stories to be completed first.

This criterion matters for several fundamental reasons:

• Flexible Prioritization: Independent stories allow the business to prioritize the backlog based strictly on value, rather than being constrained by technical dependencies (Wake 2003). Without independence, a high-priority story might be blocked by a low-priority one.
• Accurate Estimation: When stories overlap or depend on each other, their estimates become entangled. For example, if paying by Visa and paying by MasterCard are separate stories, the first one implemented bears the infrastructure cost, making the second one much cheaper (Cohn 2004). This skews estimates.
• Reduced Confusion: By avoiding overlap, independent stories reduce places where descriptions contradict each other and make it easier to verify that all needed functionality has been described (Wake 2003).

How to Evaluate It To determine if a user story is independent, ask:

1. Does this story overlap with another story? If two stories share underlying capabilities (e.g., both involve “sending a message”), they have overlap dependency—the most painful form (Wake 2003).
2. Must this story be implemented before or after another? If so, there is an order dependency. While less harmful than overlap (the business often naturally schedules these correctly), it still constrains planning (Wake 2003).
3. Was this story split along technical boundaries? If one story covers the UI layer and another covers the database layer for the same feature, they are interdependent and neither delivers value alone (Cohn 2004).

How to Improve It If stories violate the Independent criterion, you can improve them using these techniques:

• Combine Interdependent Stories: If two stories are too entangled to estimate separately, merge them into a single story. For example, instead of separate stories for Visa, MasterCard, and American Express payments, combine them: “A company can pay for a job posting with a credit card” (Cohn 2004).
• Partition Along Different Dimensions: If combining makes the story too large, re-split along a different dimension. For overlapping email stories like “Team member sends and receives messages” and “Team member sends and replies to messages”, repartition by action: “Team member sends message”, “Team member receives message”, “Team member replies to message” (Wake 2003).
• Slice Vertically: When stories have been split along technical layers (UI vs. database), re-slice them as vertical “slices of cake” that cut through all layers. Instead of “Job Seeker fills out a resume form” and “Resume data is written to the database”, write “Job Seeker can submit a resume with basic information” (Cohn 2004).

Examples of Stories Violating the Independent Criterion

Example 1: Overlap Dependency

Story A: “As a team member, I want to send and receive messages so that I can communicate with my colleagues.”

• Given I am on the messaging page, When I compose a message and click “Send”, Then the message appears in the recipient’s inbox.
• Given a colleague has sent me a message, When I open my inbox, Then I can read the message.

Story B: “As a team member, I want to reply to messages so that I can indicate which message I am responding to.”

• Given I have received a message, When I click the “Reply” button and submit my response, Then the reply is sent to the original sender.
• Given the reply has been received, When the original sender views the message, Then it is displayed as a reply to the original message.

• Negotiable: Yes. Neither story dictates a specific UI or technology.
• Valuable: Yes. Communication features are clearly valuable to users.
• Estimable: Difficult. Because both stories share the “send” capability, whichever story is implemented second has unpredictable effort—parts of it may already be done, making estimates unreliable.
• Small: Yes. Each story is a manageable chunk of work that fits within a sprint.
• Testable: Yes. Clear acceptance criteria can be written for sending, receiving, and replying.
• Why it violates Independent: Both stories include “sending a message”—this is an overlap dependency, the most harmful form of story dependency (Wake 2003). If Story A is implemented first, parts of Story B are already done. If Story B is implemented first, parts of Story A are already done. This creates confusion about what is covered and makes estimation unreliable.
• How to fix it: Make the dependency explicit (e.g., User story B depends on user story A). Merging them into one story is not an option as it would violate the small criterion, splitting them into three stories (sending, receiving and replying) is not an option as it would still violate the independent criterion and also violate valuable for just sending without receiving. So the best thing we can do is to accept that we cannot always create perfectly independent user stories and instead document this dependency so that when scheduling the implementation of user stories we can directly see that they have to be implemented in a specific order and when estimating user stories we can assume that the functionality in user story A has already been implemented. Hidden dependencies are bad. Full independence is perfect but not always achievable. Explicit dependencies are the pragmatic workaround that addresses the core problem of hidden dependencies while still acknowledging practicality.

Example 2: Technical (Horizontal) Splitting

Story A: “As a job seeker, I want to fill out a resume form so that I can enter my information.”

• Given I am on the resume page, When I fill in my name, address, and education, Then the form displays my entered information.

Story B: “As a job seeker, I want my resume data to be saved so that it is available when I return.”

• Given I have filled out the resume form, When I click “Save”, Then my resume data is available when I log back in.

• Negotiable: Yes. Neither story mandates a specific technology, database, or framework—the implementation details are open to discussion.
• Valuable: No. Neither story delivers value on its own—a form that does not save is useless, and saving data without a form to collect it is equally useless.
• Estimable: Yes. Developers can estimate each technical task.
• Small: Yes. Each is a small piece of work.
• Testable: Yes, though the horizontal split makes end-to-end testing awkward.
• Why it violates Independent: Story B is meaningless without Story A, and Story A is useless without Story B. They are completely interdependent because the feature was split along technical boundaries (UI layer vs. persistence layer) instead of user-facing functionality (Cohn 2004).
• How to fix it: Combine into a single vertical slice: “As a job seeker, I want to submit a resume with basic information (name, address, education) so that employers can find me.” This cuts through all layers and delivers value independently (Cohn 2004).

Quick Check: Consider these two stories for a music streaming app:

• Story A: “As a listener, I want to create playlists so that I can organize my music.”
• Story B: “As a listener, I want to add songs to a playlist so that I can build my collection.”

Are these stories independent? Why or why not?

Reveal Answer

They are not independent — they have an order dependency (the less harmful form, compared to overlap dependency) (Wake 2003). Story B requires playlists to exist (Story A). There are two valid approaches: (1) Combine them: "As a listener, I want to create and populate playlists so that I can organize my music." (2) Accept the dependency: Since order dependencies are less harmful than overlap dependencies, the team can keep both stories separate and simply ensure Story A is scheduled first. The business often naturally handles this ordering correctly (Wake 2003).

Negotiable

A negotiable story captures the essence of a user’s need without locking in specific design or technology decisions—the details are worked out collaboratively.

What it is and Why it Matters The “Negotiable” criterion states that a user story is not an explicit contract for features; rather, it captures the essence of a user’s need, leaving the details to be co-created by the customer and the development team during development (Wake 2003). A good story captures the essence, not the details (see also “Requirements Vs. Design”).

This criterion matters for several fundamental reasons:

• Enabling Collaboration: Because stories are intentionally incomplete, the team is forced to have conversations to fill in the details. Ron Jeffries describes this through the three C’s: Card (the story text), Conversation (the discussion), and Confirmation (the acceptance tests) (Cohn 2004). The card is merely a token promising a future conversation (Wake 2003).
• Evolutionary Design: High-level stories define capabilities without over-constraining the implementation approach (Wake 2003). This leaves room to evolve the solution from a basic form to an advanced form as the team learns more about the system’s needs.
• Avoiding False Precision: Including too many details early creates a dangerous illusion of precision (Cohn 2004). It misleads readers into believing the requirement is finalized, which discourages necessary conversations and adaptation.

How to Evaluate It To determine if a user story is negotiable, ask:

1. Does this story dictate a specific technology or design decision? Words like “MongoDB”, “HTTPS”, “REST API”, or “dropdown menu” in a story are red flags that it has left the space of requirements and entered the space of design.
2. Could the development team solve this problem using a completely different technology or layout, and would the user still be happy? If the answer is yes, the story is negotiable. If the answer is no, the story is over-constrained.
3. Does the story include UI details? Embedding user interface specifics (e.g., “a print dialog with a printer list”) introduces premature assumptions before the team fully understands the business goals (Cohn 2004).

How to Improve It If a story violates the Negotiable criterion, you can improve it using these techniques:

• Focus on the “Why”: Use “So that” clauses to clarify the underlying goal, which allows the team to negotiate the “How”.
• Specify What, Not How: Replace technology-specific language with the user need it serves. Instead of “use HTTPS”, write “keep data I send and receive confidential”.
• Define Acceptance Criteria, Not Steps: Define the outcomes that must be true, rather than the specific UI clicks or database queries required.
• Keep the UI Out as Long as Possible: Avoid embedding interface details into stories early in the project (Cohn 2004). Focus on what the user needs to accomplish, not the specific controls they will use.

Examples of Stories Violating the Negotiable Criterion

Example 1: The Technology-Specific Story

“As a subscriber, I want my profile settings saved in a MongoDB database so that they load quickly the next time I log in.”

• Given I am logged in and I change my profile settings, When I log out and log back in, Then my profile settings are still applied.

• Independent: Yes. Saving profile settings does not depend on other stories.
• Valuable: Yes. Remembering user settings is clearly valuable.
• Estimable: Yes. A developer can estimate the effort to implement settings persistence.
• Small: Yes. This is a focused piece of work.
• Testable: Yes. You can verify that settings persist across sessions.
• Why it violates Negotiable: Specifying “MongoDB” is a design decision. The user does not care where the data lives. The engineering team might realize that a relational SQL database or local browser caching is a much better fit for the application’s architecture.
• How to fix it: “As a subscriber, I want the system to remember my profile settings so that I don’t have to re-enter them every time I log in.”

Example 2: The UI-Specific Story

“As a student, I want to select my courses from a dropdown menu so that I can register for the upcoming semester.”

• Given I am on the registration page, When I select a course from the dropdown menu and click “Register”, Then the course is added to my schedule.

• Independent: Yes. Course registration does not depend on other stories.
• Valuable: Yes. Registering for courses is clearly valuable to the student.
• Estimable: Yes. Building a course selection feature is well-understood work.
• Small: Yes. This is a single, focused feature.
• Testable: Yes. You can verify that selecting a course adds it to the schedule.
• Why it violates Negotiable: “Dropdown menu” is a specific UI design decision. The user’s actual need is to select courses, which could be achieved through many different interfaces—a search bar, a visual schedule builder, a drag-and-drop interface, or even a conversational assistant. By prescribing the dropdown, the story constrains the design team before they have explored the problem space (Cohn 2004).
• How to fix it: “As a student, I want to select courses for the upcoming semester so that I can register for my classes.” Similarly, specifying protocols (e.g., “use HTTPS”), frameworks (e.g., “built with React”), or architectural patterns (e.g., “using microservices”) are all design decisions that constrain the solution space.

Quick Check: “As a restaurant owner, I want customers to scan a QR code at their table to view the menu on their phone so that I don’t have to print physical menus.”

Does this story satisfy the Negotiable criterion?

Reveal Answer

No. "Scan a QR code" prescribes a specific solution. The owner's actual need is for customers to access the menu without physical copies — this could be achieved via QR codes, NFC tags, a URL, a dedicated app, or a table-mounted tablet. A negotiable version: "As a restaurant owner, I want customers to access the menu digitally at their table so that I can eliminate printed menus."

What to do when the user really needs the specific technology?

Sometimes the required solution does indeed have to conform to the specific technology that the customer is using in their organization. In software engineering we call this a “technical constraint”. In these cases user stories are usually not the ideal format to specify these requirement in, since these technical constraints are often cross-cutting and should be included in the design of many different independent features. User stories are a mechanism to document requirements that primarily concern the functionality of the software. Other kinds of requirements, especially those that can’t be declared “done” should use different kinds of requirements specifications.

Valuable

A valuable story delivers tangible benefit to the customer, purchaser, or user—not just to the development team.

What it is and Why it Matters The “Valuable” criterion states that every user story must deliver tangible value to the customer, purchaser, or user—not just to the development team (Wake 2003). A good story focuses on the external impact of the software in the real world: if we frame stories so their impact is clear, product owners and users can understand what the stories bring and make good prioritization choices (Wake 2003).

This criterion matters for several fundamental reasons:

• Informed Prioritization: The product owner prioritizes the backlog by weighing each story’s value against its cost. If a story’s business value is opaque—because it is written in technical jargon—the customer cannot make intelligent scheduling decisions (Cohn 2004).
• Avoiding Waste: Stories that serve only the development team (e.g., refactoring for its own sake, adopting a trendy technology) consume iteration capacity without moving the product closer to its users’ goals. The IRACIS framework provides a useful lens for value: does the story Increase Revenue, Avoid Costs, or Improve Service? (Wake 2003)
• User vs. Purchaser Value: It is tempting to say every story must be valued by end-users, but that is not always correct. In enterprise environments, the purchaser may value stories that end-users do not care about (e.g., “All configuration is read from a central location” matters to the IT department managing 5,000 machines, not to daily users) (Cohn 2004).

How to Evaluate It To determine if a user story is valuable, ask:

1. Would the customer or user care if this story were dropped? If only developers would notice, the story likely lacks user-facing value.
2. Can the customer prioritize this story against others? If the story is written in “techno-speak” (e.g., “All connections go through a connection pool”), the customer cannot weigh its importance (Cohn 2004).
3. Does this story describe an external effect or an internal implementation detail? Valuable stories describe what happens on the edge of the system—the effects of the software in the world—not how the system is built internally (Wake 2003).

How to Improve It If stories violate the Valuable criterion, you can improve them using these techniques:

• Rewrite for External Impact: Translate the technical requirement into a statement of benefit for the user. Instead of “All connections to the database are through a connection pool”, write “Up to fifty users should be able to use the application with a five-user database license” (Cohn 2004).
• Let the Customer Write: The most effective way to ensure a story is valuable is to have the customer write it in the language of the business, rather than in technical jargon (Cohn 2004).
• Focus on the “So That”: A well-written “so that” clause forces the author to articulate the real-world benefit. If you cannot complete “so that [some user benefit]” without referencing technology, the story is likely not valuable.
• Complete the Acceptance Criteria: A story may appear valuable but have incomplete acceptance criteria that leave out essential functionality, effectively making the delivered feature useless.

Examples of Stories Violating the Valuable Criterion

Example 1: Incomplete Acceptance Criteria That Miss the Value

“As a travel agent, I want to search for available flights for a client’s trip so that I can find the best option for them.”

• Given the travel agent enters a departure city, destination city, and travel date, When they click “Search”, Then a list of available flights for that route is displayed.
• Given the search results are displayed, When the travel agent selects a flight from the list, Then the booking page for that flight is shown.

• Independent: Yes. Searching for flights does not depend on other stories.
• Negotiable: Yes. The story does not prescribe any specific technology, UI layout, or data source—the team is free to decide how to build the search.
• Estimable: Yes. Building a flight search with results display is well-understood work with clear scope.
• Small: Yes. A single search-and-display feature fits within a sprint.
• Testable: Yes. The given acceptance criteria can be translated into an unambiguous test with concrete steps and clear testing criteria.
• Why it violates Valuable: The story text promises real value (“find the best option”), but the acceptance criteria do not mention it. Since acceptance criteria define the scope of an acceptance implementation to the user story, these acceptance criteria accept user stories that do not implement the main functionality. A list of flight names and times is useless to a travel agent who needs to compare prices, layover durations, and total travel time to recommend the best option to a client. Without this comparison data, the agent cannot accomplish the goal stated in the “so that” clause. The feature technically works—flights are displayed and can be selected—but it does not solve the user’s actual problem. This illustrates why acceptance criteria must capture the essential functionality that delivers the value promised by the story. A story may appear valuable based on its text, but if its acceptance criteria leave out the information or capability that makes the feature genuinely useful, the delivered feature might not provide real value to the user. In this example, the acceptance criteria should help the developers understand what information is needed for the user to find the best option. Since the developers could pick any random subset of attributes their selection might not be what the user really needs to see. So our acceptance criteria should clearly communicate what it is the user really needs.
• How to fix it: Add acceptance criteria that capture the comparison capability essential to the agent’s real goal: “Given the search results are displayed, When the travel agent views the list, Then each flight shows the ticket price, number of stops, layover durations, and total travel time so the agent can compare options side by side.”

Quick Check: “As a backend developer, I want to migrate our logging from printf statements to a structured logging framework so that log entries are in JSON format.”

Does this story satisfy the Valuable criterion?

Reveal Answer

No. While this story might make it easier for developers to deliver more value to the user in the future due to better maintainability, it does not directly deliver value to a user of the system. We consider a user story valuable only if it meets the need of a user.

Example 2: The Developer-Centric Story

“As a developer, I want to refactor the authentication module so that the codebase is easier to maintain.”

• Given the authentication module has been refactored, When a developer deploys the updated module, Then all existing authentication endpoints return identical responses.

• Independent: Yes. Refactoring the auth module does not depend on other stories.
• Negotiable: Yes. The story does not dictate a specific technology, language, or design decision—the team is free to choose how to improve maintainability.
• Estimable: Yes. A developer can estimate the effort of a refactoring task.
• Small: Yes. Refactoring a single module can fit within a sprint.
• Testable: Yes. You can verify the refactored module passes all existing authentication tests.
• Why it violates Valuable: The story is written entirely from the developer’s perspective. The user does not care about internal code quality. The “so that” clause (“the codebase is easier to maintain”) describes a developer benefit, not a user benefit (Cohn 2004). A product owner cannot weigh “easier to maintain” against user-facing features.
• How to fix it: If there is a legitimate user-facing reason (e.g., performance), rewrite the story around that benefit: “As a registered member, I want to log in without noticeable delay so that I can start using the application immediately.”

Estimable

An estimable story has a scope clear enough for the development team to make a reasonable judgment about the effort required.

What it is and Why it Matters The “Estimable” criterion states that the development team must be able to make a reasonable judgment about a story’s size, cost, or time to deliver (Wake 2003). While precision is not the goal, the estimate must be useful enough for the product owner to prioritize the story against other work (Cohn 2004).

This criterion matters for several fundamental reasons:

• Enabling Prioritization: The product owner ranks stories by comparing value to cost. If a story cannot be estimated, the cost side of this equation is unknown, making informed prioritization impossible (Cohn 2004).
• Supporting Planning: Stories that cannot be estimated cannot be reliably scheduled into an iteration. Without sizing information, the team risks committing to more (or less) work than they can deliver.
• Surfacing Unknowns Early: An unestimable story is a signal that something important is not understood—either the domain, the technology, or the scope. Recognizing this early prevents costly surprises later.

How to Evaluate It Developers generally cannot estimate a story for one of three reasons (Cohn 2004):

1. Lack of Domain Knowledge: The developers do not understand the business context. For example, a story saying “New users are given a diabetic screening” could mean a simple web questionnaire or an at-home physical testing kit—without clarification, no estimate is possible (Cohn 2004).
2. Lack of Technical Knowledge: The team understands the requirement but has never worked with the required technology. For example, a team asked to expose a gRPC API when no one has experience with Protocol Buffers or gRPC cannot estimate the work (Cohn 2004).
3. The Story is Too Big: An epic like “A job seeker can find a job” encompasses so many sub-tasks and unknowns that it cannot be meaningfully sized as a single unit (Cohn 2004).

How to Improve It The approach to fixing an unestimable story depends on which barrier is blocking estimation:

• Conversation (for Domain Knowledge Gaps): Have the developers discuss the story directly with the customer. A brief conversation often reveals that the requirement is simpler (or more complex) than assumed, making estimation possible (Cohn 2004).
• Spike (for Technical Knowledge Gaps): Split the story into two: an investigative spike—a brief, time-boxed experiment to learn about the unknown technology—and the actual implementation story. The spike itself is always given a defined maximum time (e.g., “Spend exactly two days investigating credit card processing”), which makes it estimable. Once the spike is complete, the team has enough knowledge to estimate the real story (Cohn 2004).
• Disaggregate (for Stories That Are Too Big): Break the epic into smaller, constituent stories. Each smaller piece isolates a specific slice of functionality, reducing the cognitive load and making estimation tractable (Cohn 2004).

Examples of Stories Violating the Estimable Criterion

Example 1: The Unknown Domain

“As a patient, I want to receive a personalized wellness screening so that I can understand my health risks.”

• Given I am a new patient registering on the platform, When I complete the wellness screening, Then I receive a personalized health risk summary based on my answers.

• Independent: Yes. The screening feature does not depend on other stories.
• Negotiable: Yes. The specific questions and screening logic are open to discussion.
• Valuable: Yes. Personalized health screening is clearly valuable to patients.
• Small: Yes. A single screening workflow can fit within a sprint—once the scope is clarified.
• Testable: Yes. Acceptance criteria can define specific screening outcomes for specific patient profiles.
• Why it violates Estimable: The developers do not know what “personalized wellness screening” means in this context. It could be a simple 5-question web form or a complex algorithm that integrates with lab data. Without domain knowledge, the team cannot estimate the effort (Cohn 2004).
• How to fix it: Have the developers sit down with the customer (e.g., a qualified nurse or medical expert) to clarify the scope. Once the team learns it is a simple web questionnaire, they can estimate it confidently.

Example 2: The Unknown Technology

“As an enterprise customer, I want to access the system’s data through a gRPC API so that I can integrate it with my existing microservices infrastructure.”

• Given an enterprise client sends a gRPC request for user data, When the system processes the request, Then the system returns the requested data in the correct Protobuf-defined format.

• Independent: Yes. Adding an integration interface does not depend on other stories.
• Negotiable: Partially. The customer has specified gRPC, which is normally a technology choice that would violate Negotiable. However, in this case the customer’s existing microservices infrastructure genuinely requires gRPC compatibility, making it a hard constraint rather than an arbitrary design decision. The service contract and data schema remain open to discussion.

Note: Not all technology specifications violate Negotiable. When the customer’s existing infrastructure genuinely requires a specific protocol or format, that constraint is a hard requirement, not an arbitrary design choice. The key question is: could the user’s goal be met equally well with a different technology? If a gRPC customer cannot use REST, then gRPC is a requirement, not a design decision (Cohn 2004).

• Valuable: Yes. Enterprise integration is clearly valuable to the purchasing organization.
• Small: Yes. A single service endpoint can fit within a sprint—once the team understands the technology.
• Testable: Yes. You can verify the interface returns the correct data in the correct format.
• Why it violates Estimable: No one on the development team has ever built a gRPC service or worked with Protocol Buffers. They understand what the customer wants but have no experience with the technology required to deliver it, making any estimate unreliable (Cohn 2004).
• How to fix it: Split into two stories: (1) a time-boxed spike—”Investigate gRPC integration: spend at most two days building a proof-of-concept service”—and (2) the actual implementation story. After the spike, the team has enough knowledge to estimate the real work (Cohn 2004).

Quick Check: “As a content creator, I want the platform to automatically generate accurate subtitles for my uploaded videos so that my content is accessible to hearing-impaired viewers.”

The development team has never worked with speech-to-text technology. Is this story estimable?

Reveal Answer

No. The team lacks the technical knowledge required to estimate the effort — this is the "unknown technology" barrier. The fix: split into a time-boxed spike ("Spend two days evaluating speech-to-text APIs and building a proof-of-concept") and the actual implementation story. After the spike, the team will have enough experience to estimate the real work.

Small

A small story is a manageable chunk of work that can be completed within a single iteration—not so large it becomes an epic, not so small it loses meaningful context. A user story should be as small as it can be while still delivering value.

What it is and Why it Matters The “Small” criterion states that a user story should be appropriately sized so that it can be comfortably completed by the development team within a single iteration (Cohn 2004). Stories typically represent at most a few person-weeks of work; some teams restrict them to a few person-days (Wake 2003). If a story is too large, it is called an epic and must be broken down. If a story is too small, it should be combined with related stories.

This criterion matters for several fundamental reasons:

• Predictability: Large stories are notoriously difficult to estimate accurately. The smaller the story, the higher the confidence the team has in their estimate of the effort required (Cohn 2004).
• Risk Reduction: If a massive story spans an entire sprint (or spills over into multiple sprints), the team risks delivering zero value if they hit a roadblock. Smaller stories ensure a steady, continuous flow of delivered value.
• Faster Feedback: Smaller stories reach a “Done” state faster, meaning they can be tested, reviewed by the product owner, and put in front of users much sooner to gather valuable feedback.

How to Evaluate It To determine if a user story is appropriately sized, ask:

1. Is it a compound story? Words like and, or, and but in the story description (e.g., “I want to register and manage my profile and upload photos”) often indicate that multiple stories are hiding inside one. A compound story is an “epic” that aggregates multiple easily identifiable shorter stories (Cohn 2004).
2. Can it be split while still being valuable? If a user story can be split into separate stories that are still valuable then this is often a good idea. If the smaller parts do not individually satisfy valuable, we still consider the larger user story “small”.
3. Is it a complex, uncertain story? If the story is large because of inherent uncertainty (new technology, novel algorithm), it is a complex story and should be split into a spike and an implementation story (Cohn 2004).

How to Improve It The approach to fixing a story that violates the Small criterion depends on whether it is too big or too small:

Stories that are too big:

• Split by Workflow Steps (CRUD): Instead of “As a job seeker, I want to manage my resume”, split along operations: create, edit, delete, and manage multiple resumes (Cohn 2004).
• Split by Data Boundaries: Instead of splitting by operation, split by the data involved: “add/edit education”, “add/edit job history”, “add/edit salary” (Cohn 2004).
• Slice the Cake (Vertical Slicing): Never split along technical boundaries (one story for UI, one for database). Instead, split into thin end-to-end “vertical slices” where each story touches every architectural layer and delivers complete, albeit narrow, functionality (Cohn 2004).
• Split by Happy/Sad Paths: Build the “happy path” (successful transaction) as one story, and handle the error states (declined cards, expired sessions) in subsequent stories.

Examples of Stories Violating the Small Criterion

Example 1: The Epic (Too Big)

“As a traveler, I want to plan a vacation so that I can book all the arrangements I need in one place.”

• Given I have selected travel dates and a destination, When I search for vacation packages, Then I see available flights, hotels, and rental cars with pricing.
• Given I have selected a flight, hotel, and rental car, When I click “Book”, Then all reservations are confirmed and I receive a booking confirmation email.

• Independent: Yes. Planning a vacation does not overlap with other stories.
• Negotiable: Yes. The specific features and UI are open to discussion.
• Valuable: Yes. End-to-end vacation planning is clearly valuable to travelers.
• Estimable: Partially. A developer can give a rough order-of-magnitude estimate (“several months”), but the hidden complexity within this epic makes the estimate too unreliable for sprint planning. Violations of Small often cause violations of Estimable, since epics contain hidden complexity (Cohn 2004).
• Testable: Yes. Acceptance criteria can be written, though they would need to be much more detailed once the epic is broken into smaller stories.
• Why it violates Small: “Planning a vacation” involves searching for flights, comparing hotels, booking rental cars, managing an itinerary, handling payments, and much more. This is an epic containing many stories. It cannot be completed in a single sprint (Cohn 2004).
• How to fix it: Disaggregate into smaller vertical slices: “As a traveler, I want to search for flights by date and destination so that I can find available options”, “As a traveler, I want to compare hotel prices for my destination so that I can choose one within my budget”, etc.

Example 2: The Micro-Story (Too Small)

“As a job seeker, I want to edit the date for each community service entry on my resume so that I can correct mistakes.”

• Given I am viewing a community service entry on my resume, When I change the date field and click “Save”, Then the updated date is displayed on my resume.

• Independent: Yes. Editing a single date field does not depend on other stories.
• Negotiable: Yes. The exact editing interaction is open to discussion.
• Valuable: Yes. Correcting resume data is valuable to the user.
• Estimable: Yes. Editing a single field is trivially estimable.
• Testable: Yes. Clear pass/fail criteria can be written.
• Why it violates Small: This story is too small. The administrative overhead of writing, estimating, and tracking this story card takes longer than actually implementing the change. Having dozens of stories at this granularity buries the team in disconnected details—what Wake calls a “bag of leaves” (Wake 2003).
• How to fix it: Combine with related micro-stories into a single meaningful story: “As a job seeker, I want to edit all fields of my community service entries so that I can keep my resume accurate.” (Cohn 2004)

Quick Check: “As a job seeker, I want to manage my resume so that employers can find me.”

Is this story appropriately sized?

Reveal Answer

No — it is too big (an epic). "Manage my resume" hides multiple stories: create a resume, edit sections, upload a photo, delete a resume, manage multiple versions. The word "manage" is often a signal that a story is a compound epic. Split by CRUD operations: "I want to create a resume", "I want to edit my resume", "I want to delete my resume" — or by data boundaries: "I want to add/edit my education", "I want to add/edit my work history", "I want to add/edit my skills".

Testable

A testable story has clear, objective, and measurable acceptance criteria that allow the team to verify definitively when the work is done.

What it is and Why it Matters The “Testable” criterion dictates that a user story must have clear, objective, and measurable conditions that allow the team to verify when the work is officially complete. If a story is not testable, it can never truly be considered “Done”.

This criterion matters for several crucial reasons:

• Shared Understanding: It forces the product owner and the development team to align on the exact expectations. It removes ambiguity and prevents the dreaded “that’s not what I meant” conversation at the end of a sprint.
• Proving Value: A user story represents a slice of business value. If you cannot test the story, you cannot prove that it successfully delivers that value to the user.
• Enabling Quality Assurance: Testable stories allow QA engineers (and developers practicing Test-Driven Development) to write their test cases—whether manual or automated—before a single line of production code is written.

How to Evaluate It To determine if a user story is testable, ask yourself the following questions:

1. Can I write a definitive pass/fail test for this? If the answer relies on someone’s opinion or mood, it is not testable.
2. Does the story contain “weasel words”? Look out for subjective adjectives and adverbs like fast, easy, intuitive, beautiful, modern, user-friendly, robust, or seamless. These words are red flags that the story lacks objective boundaries.
3. Are the Acceptance Criteria clear? Does the story have defined boundaries that outline specific scenarios and edge cases?

How to Improve It If you find a story that violates the Testable criterion, you can improve it by replacing subjective language with quantifiable metrics and concrete scenarios:

• Quantify Adjectives: Replace subjective terms with hard numbers. Change “loads fast” to “loads in under 2 seconds”. Change “supports a lot of users” to “supports 10,000 concurrent users”.
• Use the Given/When/Then Format: Borrow from Behavior-Driven Development (BDD) to write clear acceptance criteria. Establish the starting state (Given), the action taken (When), and the expected, observable outcome (Then).
• Define “Intuitive” or “Easy”: If the goal is a “user-friendly” interface, make it testable by tying it to a metric, such as: “A new user can complete the checkout process in fewer than 3 clicks without relying on a help menu.”

Examples of Stories Violating the Testable Criterion

Below are two user stories that are not testable but still satisfy (most) other INVEST criteria.

Example 1: The Subjective UI Requirement

“As a marketing manager, I want the new campaign landing page to feature a gorgeous and modern design, so that it appeals to our younger demographic.”

• Given the landing page is deployed, When a visitor from the 18-24 demographic views it, Then the design looks gorgeous and modern.

• Independent: Yes. It doesn’t inherently rely on other features being built first.
• Negotiable: Yes. The exact layout and tech used to build it are open to discussion.
• Valuable: Yes. A landing page to attract a younger demographic provides clear business value.
• Estimable: Yes. Generally, a frontend developer can estimate the effort to build a standard landing page independent of what specific definition of “gorgeous and modern” is used.
• Small: Yes. Building a single landing page easily fits within a single sprint.
• Why it violates Testable: “Gorgeous”, “modern”, and “appeals to” are completely subjective. What one developer thinks is modern, the marketing manager might think is ugly.
• How to fix it: Tie it to a specific, measurable design system or user-testing metric. (e.g., “Acceptance Criteria: The design strictly adheres to the new V2 Brand Guidelines and passes a 5-second usability test with a 4/5 rating from a focus group of 18-24 year olds.”)

Example 2: The Vague Performance Requirement

“As a data analyst, I want the monthly sales report to generate instantly, so that my workflow isn’t interrupted by loading screens.”

• Given the database contains 5 years of sales data, When the analyst requests the monthly sales report, Then the report generates instantly.

• Independent: Yes. Optimizing or building this report can be done independently.
• Negotiable: Yes. The team can negotiate how to achieve the speed (e.g., caching, database indexing, background processing).
• Valuable: Yes. Saving the analyst’s time is a clear operational benefit.
• Estimable: Yes. A developer can estimate the effort for standard report optimizations (query tuning, caching, indexing, pagination) regardless of the specific latency threshold that will ultimately be defined. The implementation work is predictable even though the acceptance threshold is not—just as in Example 1 above, where the effort to build a landing page does not depend on the specific definition of “modern”.
• Small: Yes. It is a focused optimization on a single report.
• Why it violates Testable: “Instantly” is subjective. Does it mean 100 milliseconds? Two seconds? Zero perceived delay? Without a quantifiable threshold, QA cannot write a definitive pass/fail test—and the developer cannot know when to stop optimizing.
• How to fix it: Replace the subjective word with a quantifiable service level indicator. (e.g., “Acceptance Criteria: Given the database contains 5 years of sales data, when the analyst requests the monthly sales report, then the data renders on screen in under 2.5 seconds at the 95th percentile.”)

Example 3: The Subjective Audio Requirement

“As a podcast listener, I want the app’s default intro chime to play at a pleasant volume, so that it doesn’t startle me when I open the app.”

• Given I open the app for the first time, When the intro chime plays, Then the volume is at a pleasant level.

• Independent: Yes. Adjusting the audio volume doesn’t rely on other features.
• Negotiable: Yes. The exact decibel level or method of adjustment is open to discussion.
• Valuable: Yes. Improving user comfort directly enhances the user experience.
• Estimable: Yes. Changing a default audio volume variable or asset is a trivial, highly predictable task (e.g., a 1-point story). The developers know exactly how much effort is involved.
• Small: Yes. It will take a few minutes to implement.
• Why it violates Testable: “Pleasant volume” is entirely subjective. A volume that is pleasant in a quiet library will be inaudible on a noisy subway. Because there is no objective baseline, QA cannot definitively pass or fail the test.
• How to fix it: “Acceptance Criteria: The default intro chime must be normalized to -16 LUFS (Loudness Units relative to Full Scale).”

How INVEST supports agile processes like Scrum

The INVEST principles matter because they act as a compass for creating high-quality, actionable user stories that align with Agile goals and principles of processes like Scrum. By ensuring stories are Independent and Small, teams gain the scheduling flexibility needed to implement and release features in any order within short iterations. If user stories are not independent, it becomes hard to always select the highest value user stories. If they are not small, it becomes hard to select a Sprint Backlog that fits the team’s velocity.
Negotiable stories promote essential dialog between developers and stakeholders, while Valuable ones ensure that every effort translates into a meaningful benefit for the user. Finally, stories that are Estimable and Testable provide the clarity required for accurate sprint planning and objective verification of the finished product. In Scrum and XP, user stories are estimated during the Planning activity.

FAQ on INVEST

How are Estimable and Testable different?

Estimable refers to the ability of developers to predict the size, cost, or time required to deliver a story. This attribute relies on the story being understood well enough and having a clear enough scope to put useful bounds on those guesses.

Testable means that a story can be verified through objective acceptance criteria. A story is considered testable if there is a definitive “Yes” or “No” answer to whether its objectives have been achieved.

In practice, these two are closely linked: if a story is not testable because it uses vague terms like “fast” or “high accuracy”, it becomes nearly impossible to estimate the actual effort needed to satisfy it. But that is not always the case.

Here are examples of user stories that isolate those specific violations of the INVEST criteria:

Violates Testable but not Estimable User Story: “As a site administrator, I want the dashboard to feel snappy when I log in so that I don’t get frustrated with the interface.”

• Why it violates Testable: Terms like “snappy” or “fast” are subjective. Without a specific metric (e.g., “loads in under 2 seconds”), there is no objective “Yes” or “No” answer to determine if the story is done.
• Why it is still Estimable: The developers know the dashboard and its tech stack well. Regardless of how “snappy” is ultimately defined, they can estimate the effort for standard front-end optimizations (lazy loading, caching, query tuning) that would improve perceived responsiveness. The implementation work is predictable even though the acceptance threshold is not, because for all reasonable interpretations of snappy, the implementation effort is roughly the same, as these techniques are well understood and often available in libraries. Note: Depending on your personal experience with web development, you might evaluate this example as not estimable. That would also be a valid judgment. In that case, check out the Subjective UI Requirement Example above for another example.

Violates Estimable but not Testable User Story: “As a safety officer, I want the system to automatically identify every pedestrian in this complex, low-light video feed so that I can monitor crosswalk safety without reviewing hours of footage manually.”

• Why it violates Estimable: This is a “research project”. Because the technical implementation is unknown or highly innovative, developers cannot put useful bounds on the time or cost required to solve it.
• Why it is still Testable: It is perfectly testable; you could poll 1,000 humans to verify if the software’s identifications match reality. The outcome is clear, but the effort to reach it is not.
• What about Small? This user story also violates Small—it is a very large feature that would span multiple sprints. However, the key insight is that even if we broke it into smaller pieces, each piece would still be unestimable due to the technical uncertainty. The Estimable violation is the root cause here, not the size.

How are Estimable and Small different?

While they are related, Estimable and Small focus on different dimensions of a user story’s readiness for development.

Estimable: Predictability of Effort

Estimable refers to the developers’ ability to provide a reasonable judgment regarding the size, cost, or time required to deliver a story.

• Requirements: For a story to be estimable, it must be understood well enough and be stable enough that developers can put “useful bounds” on their guesses.
• Barriers: A story may fail this criterion if developers lack domain knowledge, technical knowledge (requiring a “technical spike” to learn), or if the story is so large (an epic) that its complexity is hidden.
• Goal: It ensures the Product Owner can prioritize stories by weighing their value against their cost.

Small: Manageability of Scope

Small refers to the physical magnitude of the work. A story should be a manageable chunk that can be completed within a single iteration or sprint.

• Ideal Size: Most teams prefer stories that represent between half a day and two weeks of work.
• Splitting: If a story is too big, it should be split into smaller, still-valuable “vertical slices” of functionality. However, a story shouldn’t be so small (like a “bag of leaves”) that it loses its meaningful context or value to the user.
• Goal: Smaller stories provide more scheduling flexibility and help maintain momentum through continuous delivery.

Key Differences

1. Nature of the Constraint: Small is a constraint on volume, while Estimable is a constraint on clarity.
2. Accuracy vs. Size: While smaller stories tend to get more accurate estimates, a story can be small but still unestimable. For example, a “Research Project” or investigative spike might involve a very small amount of work (reading one document), but because the outcome is unknown, it remains impossible to estimate the time required to actually solve the problem.
3. Predictability vs. Flow: Estimability is necessary for planning (knowing what fits in a release), while Smallness is necessary for flow (ensuring work moves through the system without bottlenecks).

Is there often a tradeoff between Small and Valuable?

Yes! When writing user stories this is one of the most common trade-offs to consider. The more valuable a user story is, the larger it becomes. When considering this trade-off the best advice would be to think of valuable as a binary dimension. Once a user story adds some reasonable value to the user, we consider it valuable. So aiming to write the smallest user stories that are still valuable is often a good approach. Optimizing for small until the user story becomes not valuable anymore. A user story can become too small when writing and estimating it takes more time than implementing it. Then it should be combined with other user stories even if the smaller user story is still somewhat valuable. Whether a user story is “good” or “bad” is not a binary criterion, but a spectrum. Aiming to reasonably improve user stories is a desirable goal, but in a practical setting, “good enough” is often sufficient while “perfect” can be a waste of time.

Is INVEST evaluated primarily on the main body of the user story or the acceptance criteria?

Since acceptance critiera define the actual scope of what defines a correct implementation of the requirement, they are the decision driver for INVEST. The main body can be seen as a gentle summary. But for INVEST the acceptance criteria usually “overrule” the main body of the user story.

Common mistakes in user stories

Acceptance criteria omit an essential step, yet the story is claimed to be “Valuable” E.g., a user story about blocking a user whose acceptance criteria include “given I have blocked a user” but never specify how the user actually performs the block.

Dependent stories are claimed to be “Independent” E.g., a story for creating a post and a story for liking a post are marked independent, even though liking requires a post to exist. E.g., a story for logging in and a story for creating or liking a post are marked independent, even though the latter presupposes authentication.

”So that…” is circular or merely restates the feature E.g., “As a user, I want to like/unlike a post on my feed so that I can engage and interact with the content.” Engage is just a synonym for like/unlike, and content is just a synonym for post — the rationale explains nothing. A good “so that” states the underlying motivation: e.g., “so that I can signal approval to the author.”

Acceptance criteria are missing the key assertion E.g., “Given I am on the login screen, when I enter the correct email and password and click Login, then I should be redirected to the home screen.” Being redirected to the home screen does not confirm a successful login. The criterion should also assert that the user is authenticated — for example, that their name appears in the header or that they can access protected content.

Applicability

User stories are ideal for iterative, customer-centric projects where requirements might change frequently.

Limitations

User stories can struggle to capture non-functional requirements like performance, security, or reliability, and they are generally considered insufficient for safety-critical systems like spacecraft or medical devices.

Practice

Acknowledgements

Thanks to Allison Gao for constructive suggestions on how to improve this chapter.

Unified Modeling Language (UML)

Why Model?

Before writing a single line of code, software engineers need to communicate their ideas clearly. Consider a team of four developers asked to build “a building management system”. Without a shared model, each person imagines something different—one pictures a skyscraper, another a shopping mall, a third a house. A model gives the team a shared blueprint to align on, just like an architectural drawing does for a construction crew.

Modeling serves two critical purposes in software engineering:

1. Communication. Models provide a common, simple, graphical representation that allows developers, architects, and stakeholders to discuss the workings of the software. When everyone reads the same diagram, the team converges on the same understanding.

2. Early Problem Detection. Fixing bugs found during design costs a fraction of fixing bugs found during testing or maintenance. Studies have suggested that the cost to fix a defect grows substantially from the requirements phase to the maintenance phase — common estimates range from 10× to 100× depending on the project and phase (Boehm, Software Engineering Economics, 1981; McConnell, Code Complete, 2nd ed., 2004). The empirical strength of the 100× claim is debated (see Bossavit, The Leprechauns of Software Engineering, 2015), but the qualitative principle — earlier defects are cheaper to fix — is widely accepted. Modeling and analysis shifts the discovery of problems earlier in the lifecycle, where they are cheaper to fix.

What Is a Model?

A model describes a system at a high level of abstraction. Models are abstractions of a real-world artifact (software or otherwise) produced through an abstraction function that preserves the essential properties while discarding irrelevant detail. Models can be:

• Descriptive: Documenting an existing system (e.g., reverse-engineering a legacy codebase).
• Prescriptive: Specifying a system that is yet to be built (e.g., designing a new feature).

A Brief History of UML

In the 1980s, the rise of Object-Oriented Programming spawned dozens of competing modeling notations. By the mid-1990s, more than 50 OO modeling methods had been proposed. The three leading notation designers — Grady Booch (Booch method), Jim Rumbaugh (OMT — Object Modeling Technique), and Ivar Jacobson (OOSE — Object-Oriented Software Engineering) — converged at Rational Software and combined their approaches. This convergence, standardized by the Object Management Group (OMG) in 1997, produced UML 1.x (UML 1.1 was the first OMG-adopted version). UML 2.0 was adopted by the OMG in 2003 and finalized in 2005 (see Rumbaugh, Jacobson & Booch, The Unified Modeling Language Reference Manual, 2nd ed., 2004). The current version, UML 2.5.1 (2017), is maintained by the OMG.

UML is a large language — the current UML 2.5.1 specification spans nearly 800 pages — but in practice only a small fraction of its notation is widely used. Martin Fowler (UML Distilled) advocates learning the “mythical 20 percent of UML that helps you do 80 percent of your work”, and recommends sketching-level UML over exhaustive coverage of every symbol. This textbook follows that philosophy.

Modeling Guidelines

• Purpose first. Before drawing, decide why the diagram exists: requirements gathering, analysis, design, or documentation. Each level shows different detail (Ambler, The Elements of UML 2.0 Style, G87–G88).
• Nearly everything in UML is optional — you choose how much detail to show.
• Models are rarely complete. They capture only the aspects relevant to the question at hand (Fowler’s “Depict Models Simply” principle).
• UML is open to interpretation and designed to be extended via profiles and stereotypes.
• 7±2 rule: Keep a single diagram to roughly 9 elements or fewer. If a diagram grows past that, split it — the cognitive load of reading it exceeds working memory.

UML Diagram Types

UML diagrams fall into two broad categories:

Static Modeling (Structure)

Static diagrams capture the fixed, code-level relationships in the system:

• Class Diagrams (widely used) — Show classes, their attributes, operations, and relationships.
• Package Diagrams — Group related classes into packages.
• Component Diagrams (widely used) — Show high-level components and their interfaces.
• Deployment Diagrams — Show the physical deployment of software onto hardware.

Behavioral Modeling (Dynamic)

Behavioral diagrams capture the dynamic execution of a system:

• Use Case Diagrams (widely used) — Capture requirements from the user’s perspective.
• Sequence Diagrams (widely used) — Show time-based message exchange between objects.
• State Machine Diagrams (widely used) — Model an object’s lifecycle through state transitions.
• Activity Diagrams (widely used) — Model workflows and concurrent processes.
• Communication Diagrams — Show the same information as sequence diagrams, organized by object links rather than time.

In this textbook, we focus in depth on the five most widely used diagram types: Use Case Diagrams, Class Diagrams, Sequence Diagrams, State Machine Diagrams, and Component Diagrams.

Quick Preview

Here is a taste of each diagram type. Each is covered in detail in its own chapter.

Class Diagram

Sequence Diagram

State Machine Diagram

Use Case Diagram

UML Use Case Diagrams

Learning Objectives

By the end of this chapter, you will be able to:

1. Identify the core elements of a use case diagram: actors, use cases, system boundaries, and associations.
2. Differentiate between include, extend, and generalization relationships between use cases.
3. Translate a written description of system requirements into a use case diagram.
4. Evaluate when use case diagrams are appropriate versus other UML diagram types.

1. Introduction: Requirements from the User’s Perspective

Before diving into the internal design of a system (class diagrams, sequence diagrams), we need to answer a fundamental question: What should the system do? Use case diagrams capture the requirements of a system from the user’s perspective. They show the functionality a system must provide and which types of users interact with each piece of functionality.

A use case refers to a particular piece of functionality that the system must provide to a user—similar to a user story. Use cases are at a higher level of abstraction than other UML elements. While class diagrams model the code structure and sequence diagrams model object interactions, use case diagrams model the system’s goals from the outside looking in.

Concept Check (Generation): Before reading further, try to list 4-5 things a user might want to do with an online bookstore. What types of users might there be? Write your answers down, then compare them to the examples below.

2. Core Elements

2.1 Actors

An actor represents a role played by a user, or any other system, that interacts with the subject of a use case (UML 2.5.1 §18.2.1). The most common notation is a stick figure with the role name below, but the spec defines three equivalent notations: a stick figure (Figure 18.6), a class rectangle with the keyword «actor» (Figure 18.7), or a custom icon that conveys the kind of actor — for example a screen-and-keyboard icon for a non-human external system (Figure 18.8). Any of the three may be used for any actor; the choice is stylistic, not semantic.

Key points about actors:

• An actor is a role, not a specific person. One person can play multiple roles (e.g., a university professor might be both an “Instructor” and a “Student” in a course system).
• A single user may be represented by multiple actors if they interact with different parts of the system in different capacities.
• Actors are always external to the subject — they interact with it but are not part of it.

⚠ Roles, not job titles (Ambler G65). Name actors for the role they play in this system, not for their position in a company. “Customer”, “Instructor”, “Support Agent” — good. “Senior VP of Sales”, “Junior CSR” — bad. Job titles change when HR reorganises; roles describe what the system cares about. The same rule applies to our auto-memory guidance: user-story actors must always be real users, never “As a system”.

Non-human actors exist. An actor can be an external system (a payment gateway, an email provider) or even Time itself — Ambler and Seidl et al. both recommend introducing a Time actor for use cases triggered on a schedule (payroll, monthly statements, nightly batch jobs). The actor convention keeps the diagram honest: something initiates every use case.

2.2 Use Cases

A use case represents a specific goal or piece of functionality the system provides. Use cases are drawn as ovals (ellipses) containing the use case name.

• Use case names should describe a goal using a verb phrase (e.g., “Place Order”, not “Order” or “OrderSystem”).
• There will be one or more use cases per kind of actor. It is common for any reasonable system to have many use cases.

2.3 Subject (System Boundary)

The rectangle drawn around the use cases is called the subject in the UML 2.5.1 specification — though “system boundary” is the term most textbooks and tools use, and the spec acknowledges it (§18.1.4: “A subject (sometimes called a system boundary)…”). The subject represents the system (or component, or class) that realizes the contained use cases. The subject’s name appears at the top of the rectangle. Actors are placed outside the subject, and use cases are placed inside.

2.4 Associations

An association is a line drawn from an actor to a use case, indicating that the actor participates in that use case.

Putting the Basics Together

Here is a use case diagram for an automatic train system (an unmanned people-mover like those found in airports):

Reading this diagram: A Passenger can Ride the train, and a Technician can Repair the train. Both are roles (actors) external to the system.

3. Use Case Descriptions

A use case diagram shows what functionality exists, but not how it works. To capture the details, each use case should have a written use case description that includes:

• Name: A concise verb phrase (e.g., “Normal Train Ride”).
• Actors: Which actors participate (e.g., Passenger).
• Entry Condition: What must be true before this use case begins (e.g., Passenger is at station).
• Exit Condition: What is true when the use case ends (e.g., Passenger has left the station).
• Event Flow: A numbered list of steps describing the interaction.

Example: Normal Train Ride

Event Flow:

1. Passenger arrives and presses the request button.
2. Train arrives and stops at the platform.
3. Doors open.
4. Passenger steps into the train.
5. Doors close.
6. Passenger presses the request button for their final stop.
7. Doors open at the final stop.
8. Passenger exits the train.

Concept Check (Self-Explanation): Look at the event flow above. What would a non-functional requirement for this system look like? (Hint: Think about timing, safety, or capacity.) Non-functional requirements are not captured in use case diagrams—they are typically captured as Quality Attribute Scenarios.

4. Relationships Between Use Cases

Use cases rarely exist in isolation. UML defines three types of relationships between use cases: inclusion, extension, and generalization. Each is drawn as a dashed or solid arrow between use cases.

Notation Rule: For include and extend arrows, the arrows are dashed with an open arrowhead (UML 2.5.1 §18.1.4) and point in the reading direction of the verb. The relationship label is written in guillemets — the spec uses «include» and «extend»; the ASCII shorthand <<include>> / <<extend>> used throughout this chapter is universally accepted by tools and equivalent. Use the base form of the verb (e.g., «include», not «includes»).

4.1 Inclusion (<<include>>)

A use case can include the behavior of another use case. This means the included behavior always occurs as part of the including use case. Think of it as mandatory sub-behavior that has been factored out because multiple use cases share it.

Reading this diagram: Whenever a customer Purchases an Item, they always Login. Whenever they Track Packages, they also always Login. The Login behavior is shared, so it is factored out into its own use case and included by both.

Key insight: The arrow points from the including use case to the included use case (from “Purchase Item” to “Login”).

4.2 Extension (<<extend>>)

A use case extension encapsulates a distinct flow of events that is not part of the normal or basic flow but may optionally extend an existing use case. Think of it as an optional, exceptional, or conditional behavior.

Extension points (optional). A base use case can declare specific named points inside its flow where extensions may plug in — the <<extend>> relationship can name which point it attaches to, and an optional {condition} note on a dashed comment line states when the extension fires. Ambler (G83) advises skipping extension points on diagrams unless the flow is genuinely ambiguous — the detail usually fits better inside the textual use case description than on the picture.

Reading this diagram: When a customer purchases an item, debug info can (optionally) be logged in some cases. The extension is not part of the normal flow.

Key insight: The arrow points from the extending use case to the base use case (from “Log Debug Info” to “Purchase Item”). This is the opposite direction from <<include>>.

4.3 Generalization

Just like class generalization, a specialized use case can replace or enhance the behavior of a generalized use case. Generalization uses a solid line with a hollow triangle arrowhead pointing to the generalized (parent) use case.

Reading this diagram: “Synchronize Wirelessly” and “Synchronize Serially” are both specialized versions of “Synchronize Data”. Either can be used wherever the general “Synchronize Data” use case is expected.

Concept Check (Retrieval Practice): Without looking at the diagrams above, answer: Which direction does the <<include>> arrow point? Which direction does the <<extend>> arrow point? What arrowhead style does generalization use?

Reveal Answer

<<include>> points from the including use case to the included use case. <<extend>> points from the extending use case to the base use case. Generalization uses a solid line with a hollow triangle.

5. Include vs. Extend: A Comparison

Students often confuse <<include>> and <<extend>>. Here is a direct comparison:

6. Putting It All Together: Library System

Let’s read a complete use case diagram that combines all the elements we have learned.

System Walkthrough

1. Actors: There is one actor, Customer, who interacts with the library system.
2. Use Cases: The system provides three pieces of functionality: Loan Book, Borrow Book, and Check Identity.
3. Associations: The Customer can Loan a Book or Borrow a Book.
4. Inclusion: Both Loan Book and Borrow Book always include checking the customer’s identity. This shared behavior is factored out rather than duplicated.

Think-Pair-Share: In English, describe what this use case diagram says. What would happen if we added an <<extend>> relationship from a new use case “Charge Late Fee” to “Loan Book”?

Real-World Examples

These three examples show use case diagrams applied to modern platforms. Pay close attention to the direction of arrows and the distinction between <<include>> (always happens) and <<extend>> (sometimes happens) — this is the most commonly confused aspect of use case diagrams.

Example 1: GitHub — Repository Collaboration

Scenario: A shared codebase has three types of actors: contributors who submit code, maintainers who review and merge, and an automated CI bot. CI checks are mandatory before merging — this is an <<include>>, not an <<extend>>.

Reading the diagram:

1. CI Bot as a non-human actor: Actors don’t have to be people. Any external role that interacts with the system qualifies — automated services, payment providers, external APIs. The CI bot initiates the Run CI Checks use case just as a human would trigger any other.
2. <<include>> (Create PR → Authenticate): You cannot create a PR without being logged in. This is mandatory, unconditional behavior — <<include>> is correct. The arrow points from the base toward the included behavior.
3. <<include>> (Merge PR → Run CI Checks): A maintainer cannot merge without CI passing. The checks run automatically as part of every merge — they are not optional. This is another <<include>>.
4. What is NOT shown: There is no <<extend>> here, because there is no optional behavior in this workflow. Not every use case diagram needs <<extend>> — use it only when behavior genuinely sometimes happens.
5. Modeling simplification: In reality every GitHub action requires authentication, so Review Code and Merge Pull Request would each <<include>> Authenticate too. We show authentication only on Create Pull Request to keep the diagram readable — don’t read this as “review and merge are unauthenticated”. Real diagrams often face the same trade-off between completeness and clarity.

Example 2: Airbnb — Accommodation Booking

Scenario: Guests search and book; hosts list properties; payment is handled by an external service. Leaving a review is optional behavior that extends the booking flow — making this an <<extend>>.

Reading the diagram:

1. <<include>> (Booking → Payment): Every booking always processes payment. There is no booking without payment — the arrow points from Book Accommodation toward Process Payment.
2. <<extend>> (Review → Booking): A guest may leave a review after a booking, but they don’t have to. The <<extend>> arrow points from the optional use case (Leave Review) toward the base use case (Book Accommodation) — the opposite direction from <<include>>.
3. Payment Service as an external actor: The payment provider lives outside the Airbnb platform boundary. Showing it as an actor with an association to Process Payment makes the external dependency visible in the requirements model.
4. Arrow direction summary: <<include>> points toward the behavior that is always included; <<extend>> points toward the base use case being sometimes extended. Both use dashed arrows — only the direction differs.

Example 3: University LMS — Canvas-Style Learning Platform

Scenario: Students submit assignments and view grades; instructors grade and post announcements. Both roles require authentication for sensitive operations. Email notifications are optional — they extend the announcement flow.

Reading the diagram:

1. Multiple use cases sharing one <<include>> target: Both Submit Assignment and Grade Submission include Authenticate. This is the real value of <<include>> — one shared behavior, referenced from many places, maintained in one spot. If authentication changes, you update it once.
2. <<extend>> for optional notification: Send Email Notification extends Post Announcement. Sometimes an instructor sends an email alongside the announcement, sometimes they don’t. <<extend>> captures this conditionality.
3. Role separation: Students and Instructors have distinct, non-overlapping primary interactions. A student cannot grade; an instructor is not shown submitting assignments. The diagram communicates the access control model at a glance.
4. Authenticate has no actor association: Authenticate is never triggered directly by an actor — it is always triggered by another use case (<<include>>). This is correct — actors initiate top-level use cases, not shared sub-behaviors.

⚠ Common Use Case Diagram Mistakes

7. Active Recall Challenge

Grab a blank piece of paper. Without looking at this chapter, try to draw the use case diagram for the following scenario:

1. A Student can Enroll in Course and View Grades.
2. A Professor can Create Course and Submit Grades.
3. Both Enroll in Course and Create Course always include Authenticate (login).
4. View Grades can optionally be extended by Export Transcript.

After drawing, review your diagram against the rules in sections 2-4. Check: Are your arrows pointing in the correct direction? Did you use dashed lines for include/extend?

8. Interactive Practice

Test your knowledge with these retrieval practice exercises.

Knowledge Quiz

Retrieval Flashcards

Pedagogical Tip: If you find these challenging, it’s a good sign! Effortful retrieval is exactly what builds durable mental models. Try coming back to these tomorrow to benefit from spacing and interleaving.

Introduction

Pedagogical Note: This chapter is designed using principles of Active Engagement (frequent retrieval practice). We will build concepts incrementally. Please complete the “Quick Checks” without looking back at the text—this introduces a “desirable difficulty” that strengthens long-term memory.

🎯 Learning Objectives

By the end of this chapter, you will be able to:

1. Translate real-world object relationships into UML Class Diagrams.
2. Differentiate between structural relationships (Association, Aggregation, Composition).
3. Read and interpret system architecture from UML class diagrams.

Diagram – The Blueprint of Software

Imagine you are an architect designing a complex building. Before laying a single brick, you need blueprints. In software engineering, we use similar models. The Unified Modeling Language (UML) is the most common one. Among UML diagrams, Class Diagrams are the most common ones, because they are very close to the code. They describe the static structure of a system by showing the system’s classes, their attributes, operations (methods), and the relationships among objects.

The Core Building Blocks

2.1 Classes

A Class is a template for creating objects. In UML, a class is represented by a rectangle divided into three compartments:

1. Top: The Class Name.
2. Middle: Attributes (variables/state).
3. Bottom: Operations (methods/behavior).

2.2 Modifiers (Visibility)

To enforce encapsulation, UML uses symbols to define who can access attributes and operations:

• + Public: Accessible from anywhere.
• - Private: Accessible only within the class.
• # Protected: Accessible within the class and its subclasses.
• ~ Package/Default: Accessible by any class in the same package.

2.3 Interfaces

An Interface represents a contract. It tells us what a class must do, but not how it does it. It is denoted by the <<interface>> stereotype. Interfaces contain method signatures and usually do not declare attributes (the UML specification allows it, but I recommend not to use it)

Quick Check 1 (Retrieval Practice) Cover the screen above. What do the symbols +, -, and # stand for? Why does an interface lack an attributes compartment?

Connecting the Dots: Relationships

Software is never just one class working in isolation. Classes interact. We represent these interactions with different types of lines and arrows.

Generalization — “Is-A” Relationships

Generalization connects a subclass to a superclass. It means the subclass inherits attributes and behaviors from the parent.

• UML Symbol: A solid line with a hollow, closed arrow pointing to the parent.

Interface Realization

When a class agrees to implement the methods defined in an interface, it “realizes” the interface.

• UML Symbol: A dashed line with a hollow, closed arrow pointing to the interface.

Dependency (Weakest Relationship)

A dependency indicates that one class uses another, but does not hold a permanent reference to it. For example, a class might use another class as a method parameter, local variable, or return type. Dependency is the weakest relationship in a class diagram.

• UML Symbol: A dashed line with an open arrowhead.

In this example, Train depends on ButtonPressedEvent because it uses it as a parameter type in addStop(). However, Train does not store a permanent reference to ButtonPressedEvent—the dependency exists only for the duration of the method call.

Here is another example where a class depends on an exception it throws:

Association — “Has-A” / “Knows-A” Relationships

A basic structural relationship indicating that objects of one class are connected to objects of another (e.g., a “Teacher” knows about a “Student”). Attributes can also be represented as association lines: a line is drawn between the owning class and the target attribute’s class, providing a quick visual indication of which classes are related.

• UML Symbol: A simple solid line.
• You can also name associations and make them directional using an arrowhead to indicate navigability (which class holds a reference to the other).

Multiplicities

Along association lines, we use numbers to define how many objects are involved. Always show multiplicity on both ends of an association.

Navigability

When neither end of an association is annotated with an arrowhead or X mark, navigability is formally undefined in UML 2.5. By convention, many authors and tools render this case as bidirectional (both classes know about each other), but you should not rely on the default — make navigability explicit when it matters. In practice, the relationship is often one-way: only one class holds a reference to the other. UML uses arrowheads and X marks to show this navigability.

• Navigable end An open arrowhead pointing to the class that can be “reached”. The left object has a reference to the right object.
• Non-Navigable end An X on the end that cannot be navigated. This explicitly states that the class at the X end does not hold a reference to the other.

Here are the four navigability combinations, each with an example:

Unidirectional (one arrowhead): Only one class holds a reference.

Vote holds a reference to Politician, but Politician does not know about individual Vote objects.

Bidirectional (arrowheads on both ends): Both classes hold a reference to each other.

Employee knows about their Boss, and Boss knows about their Employee. Note that a plain line with no arrowheads on either end has unspecified navigability per UML 2.5 — not “bidirectional by default.” If you mean both directions are navigable, draw arrowheads on both ends (as above) to make that explicit.

Non-navigable on one end (X on one side): One class is explicitly prevented from navigating.

In the full UML notation, an X on the Voter end means that the opposite lifeline cannot navigate to it — i.e., Vote does not hold a reference back to Voter. (Voter’s navigability toward Vote is then determined by whatever is marked on the Vote end.) Note: the X mark is a formal UML 2 notation that many simplified tools do not render, and per UML 2.5, when one end carries a navigability arrow but the other end is unmarked, the unmarked end’s navigability is formally undefined, not “non-navigable” by default.

Non-navigable on both ends (X on both sides): Neither class holds a reference—the association is recorded only in the model, not in code.

An X on both ends of AccountClearTextPassword means neither class should store a reference to the other. This is a deliberate design decision (e.g., for security: an Account should never hold a reference to a ClearTextPassword).

When to use navigability: Navigability is a design-level detail. In analysis/domain models, plain associations (no arrowheads) are preferred because you haven’t decided which class holds the reference yet. Once you move into detailed design, add navigability to show which class stores the reference—this maps directly to code (a field/attribute in the class at the arrow tail).

Aggregation (“Owns-A”)

A specialized association where one class belongs to a collection, but the parts can exist independently of the whole. If a University closes down, the Professors still exist. Think of aggregation as a long-term, whole-part association.

• UML Symbol: A solid line with an empty diamond at the “whole” end.

Composition (“Is-Made-Up-Of”)

A strict relationship where the parts cannot exist without the whole. If you destroy a House, the Rooms inside it are also destroyed. A part may belong to only one composite at a time (exclusive ownership), and the composite has sole responsibility for the lifetime of its parts.

• UML Symbol: A solid line with a filled diamond at the “whole” end.
• Per the UML spec, the multiplicity on the composite end must be 1 or 0..1.

A helpful way to think about the difference: In C++, aggregation is usually expressed through pointers/references (the part can exist separately), while composition is expressed by containing instances by value (the part’s lifetime is tied to the whole). In Java and Python, every object reference is effectively a pointer — the distinction between aggregation and composition is communicated through design intent (who created the part? who destroys it?) rather than through language syntax. Inner classes in Java are one indicator of composition but are not required.

⚠ Honest caveat on aggregation. Aggregation has intentionally informal semantics in the UML 2 specification. Martin Fowler (UML Distilled) observes: “Aggregation is strictly meaningless; as a result, I recommend that you ignore it in your own diagrams.” When you aren’t sure whether something is aggregation or plain association, use association — it is always safe. Reserve the hollow diamond for the cases where part-whole semantics clearly add communicative value.

Quick Check 2 (Self-Explanation) In your own words, explain the difference between the empty diamond (Aggregation) and the filled diamond (Composition). Give a real-world example of each that is not mentioned in this text.

Relationship Strength Summary

From weakest to strongest, the class relationships are:

⚠ The Five Most Common UML Class Diagram Mistakes

Empirical studies of student diagrams (Chren et al., “Mistakes in UML Diagrams: Analysis of Student Projects in a Software Engineering Course”, ICSE SEET 2019) identify these recurring errors. Watch for them in your own work:

Pedagogy tip: Before turning in any class diagram, run this five-item checklist over every relationship. Catching these five mistakes catches the majority of grading-level errors.

Advanced Class Notation

Abstract Classes and Operations

An abstract class is a class that cannot be instantiated directly—it serves as a base for subclasses. In UML, an abstract class is indicated by italicizing the class name or adding {abstract}.

An abstract operation is a method with no implementation, intended to be supplied by descendant classes. Abstract operations are shown by italicizing the operation name.

In this example, Shape is abstract (it cannot be created directly) and declares an abstract draw() method. Rectangle inherits from Shape and provides a concrete implementation of draw().

Static Members

Static (class-level) attributes and operations belong to the class itself rather than to individual instances. In UML, static members are shown underlined.

From Code to Diagram: Worked Examples

A key skill is translating between code and UML class diagrams. Let’s work through several examples that progressively build this skill.

Example 1: A Simple Class

public class BaseSynchronizer {
    public void synchronizationStarted() { }
}

class BaseSynchronizer {
public:
    void synchronizationStarted() { }
};

class BaseSynchronizer:
    def synchronization_started(self) -> None:
        pass

class BaseSynchronizer {
  synchronizationStarted(): void { }
}

Each public method becomes a + operation in the bottom compartment. The return type follows a colon after the method signature.

Example 2: Attributes and Associations

When a class holds a reference to another class, you can show it either as an attribute or as an association line (but be consistent throughout your diagram).

public class Student {
    Roster roster;

    public void storeRoster(Roster r) {
        roster = r;
    }
}

class Roster { }

class Roster { };

class Student {
public:
    void storeRoster(Roster& r) {
        roster = &r;
    }

private:
    Roster* roster = nullptr;
};

class Roster:
    pass


class Student:
    def __init__(self) -> None:
        self._roster: Roster | None = None

    def store_roster(self, roster: Roster) -> None:
        self._roster = roster

class Roster { }

class Student {
  private roster?: Roster;

  storeRoster(roster: Roster): void {
    this.roster = roster;
  }
}

Notice: in the Java version, the roster field has package visibility (~) because no access modifier was specified (Java default is package-private). Other languages express visibility differently, but the relationship is the same: Student holds a reference to a Roster.

Example 3: Dependency from Exception Handling

public class ChecksumValidator {
    public boolean execute() {
        try {
            this.validate();
        } catch (InvalidChecksumException e) {
            // handle error
        }
        return true;
    }
    public void validate() throws InvalidChecksumException { }
}

class InvalidChecksumException extends Exception { }

#include <exception>

class InvalidChecksumException : public std::exception { };

class ChecksumValidator {
public:
    bool execute() {
        try {
            validate();
        } catch (const InvalidChecksumException&) {
            // handle error
        }
        return true;
    }

    void validate() { }
};

class InvalidChecksumException(Exception):
    pass


class ChecksumValidator:
    def execute(self) -> bool:
        try:
            self.validate()
        except InvalidChecksumException:
            # handle error
            pass
        return True

    def validate(self) -> None:
        pass

class InvalidChecksumException extends Error { }

class ChecksumValidator {
  execute(): boolean {
    try {
      this.validate();
    } catch (error) {
      if (!(error instanceof InvalidChecksumException)) throw error;
      // handle error
    }
    return true;
  }

  validate(): void { }
}

The ChecksumValidator depends on InvalidChecksumException (it uses it in a throws clause and catch block) but does not store a permanent reference to it. This is a dependency, not an association.

Example 4: Composition from Inner Classes

public class MotherBoard {
    private class IDEBus { }

    private final IDEBus primaryIDE = new IDEBus();
    private final IDEBus secondaryIDE = new IDEBus();
}

class MotherBoard {
    class IDEBus { };

    IDEBus primaryIDE;
    IDEBus secondaryIDE;
};

class MotherBoard:
    class _IDEBus:
        pass

    def __init__(self) -> None:
        self._primary_ide = MotherBoard._IDEBus()
        self._secondary_ide = MotherBoard._IDEBus()

class IDEBus { }

class MotherBoard {
  private readonly primaryIDE = new IDEBus();
  private readonly secondaryIDE = new IDEBus();
}

The private part type plus owned fields indicate composition: the IDEBus instances are created and controlled by the MotherBoard.

Quick Check (Generation): Before looking at the answer below, try to draw the UML class diagram for this code:

import java.util.ArrayList;
import java.util.List;
public class Division {
    private List<Employee> division = new ArrayList<>();
    private Employee[] employees = new Employee[10];
}

Reveal Answer

The List<Employee> field suggests aggregation (the collection can grow dynamically, employees can exist independently). The array with a fixed size of 10 is a direct association with a specific multiplicity.

Putting It All Together: The E-Commerce System

Pedagogical Note: We are now combining isolated concepts into a complex schema. This reflects how you will encounter UML in the real world.

Let’s read the architectural blueprint for a simplified E-Commerce system.

System Walkthrough:

1. Generalization: VIP and Guest are specific types of Customer.
2. Association (Multiplicity): 1 Customer can have * (zero to many) Orders.
3. Interface Realization: Order implements the Billable interface.
4. Composition: An Order strongly contains 1..* (one or more) LineItems. If the order is deleted, the line items are deleted.
5. Association: Each LineItem points to exactly 1 Product.

Real-World Examples

The following examples apply everything from this chapter to systems you interact with every day. Try reading each diagram yourself before the walkthrough — this is retrieval practice in action.

Example 1: Spotify — Music Streaming Domain Model

Scenario: An analysis-level domain model for a music streaming service. The goal is to capture what things are and how they relate — not implementation details like database schemas or network calls.

What the UML notation captures:

1. Generalization (hollow triangle): FreeUser and PremiumUser both extend User, inheriting search() and createPlaylist(). Only PremiumUser adds download() — a capability unlocked by upgrading. The hollow triangle always points up toward the parent class.
2. Composition (filled diamond, User → Playlist): A User owns their playlists. Deleting a user account deletes their playlists — the parts cannot outlive the whole. The filled diamond sits on the owner’s side.
3. Aggregation (hollow diamond, Playlist → Track): A Playlist contains tracks, but tracks exist independently — the same track can appear in many playlists. Deleting a playlist does not remove the track from the catalog.
4. Association with multiplicity (Track → Artist): Each track is performed by 1..* artists — at least one (solo) or more (collaboration). This multiplicity directly encodes a real business rule.

Analysis vs. design level: This diagram has no visibility modifiers (+, -). That is intentional — at the analysis level we model what things are and do, not encapsulation decisions. Visibility is a design-level concern added in a later phase.

Example 2: GitHub — Pull Request Design Model

Scenario: A design-level diagram (note the visibility modifiers) showing how GitHub’s code review system could be modeled internally. Notice how an interface creates a formal contract between components.

What the UML notation captures:

1. Interface Realization (dashed hollow arrow): PullRequest implements Mergeable — a contract committing the class to provide canMerge() and merge(). A merge pipeline can work with any Mergeable object without knowing the concrete type.
2. Composition (Repository → PullRequest): A PR cannot exist without its repository. Delete the repo, and all its PRs are deleted — the filled diamond on Repository’s side shows ownership.
3. Composition (PullRequest → Review): A review only exists in the context of one PR. 1 *-- * reads: one PR can have zero or more reviews; each review belongs to exactly one PR.
4. Dependency (dashed open arrow, PullRequest → CICheck): PullRequest uses CICheck temporarily — perhaps receiving it as a method parameter. It does not hold a permanent field reference, so this is a dependency, not an association.

Example 3: Uber Eats — Food Delivery Domain Model

Scenario: The domain model for a food delivery platform. This example is excellent for practicing multiplicity — every 0..1, 1, and * encodes a real business rule the engineering team must enforce.

What the UML notation captures:

1. Customer "1" -- "*" Order: One customer can have zero orders (a new account) or many. The navigability arrow shows Customer holds the reference — in code, a Customer would have an orders collection field.
2. Composition (Order → OrderItem): Order items only exist within an order. Cancelling the order destroys the items. The 1..* on OrderItem enforces that every order must have at least one item.
3. OrderItem "*" -- "1" MenuItem: Each item references exactly one menu item. Many orders can reference the same menu item — deleting an order does not remove the menu item from the restaurant’s catalog.
4. Driver "0..1" -- "0..1" Order: A driver handles at most one active delivery at a time; an order has at most one assigned driver. Before dispatch, both sides satisfy 0 — neither requires the other to exist yet. This captures a real business constraint in two characters.

Example 4: Netflix — Content Catalogue Model

Scenario: Netflix serves two fundamentally different types of content — movies (watched once) and TV shows (composed of seasons and episodes). This diagram shows how inheritance and composition work together to model a content catalog.

What the UML notation captures:

1. Abstract class (abstract class Content): The italicised class name and {abstract} on play() signal that Content is never instantiated directly — you never watch a “content”, only a Movie or an Episode. Movie overrides play() with its own implementation. TVShow is also abstract (it inherits play() without overriding it) — you don’t play a show as a whole, you play one of its Episodes, which provides its own concrete play().
2. Generalization hierarchy: Both Movie and TVShow extend Content, inheriting title and rating. A Movie adds duration directly; a TVShow delegates duration implicitly through its episodes.
3. Nested composition (TVShow → Season → Episode): A TVShow is composed of seasons; each season is composed of episodes. Delete a show and the seasons disappear; delete a season and the episodes disappear. The chain of filled diamonds models this cascade.
4. Association with multiplicity (Content → Genre): A movie or show belongs to 1..* genres (at least one — e.g., Action). A genre classifies * content items. This is a plain association — deleting a genre does not delete the content.

Example 5: Strategy Pattern — Pluggable Payment Processing

Scenario: A shopping cart needs to support multiple payment methods (credit card, PayPal, crypto) and let users switch between them at runtime. This is the Strategy design pattern — and a class diagram is the canonical way to document it.

What the UML notation captures:

1. Interface as contract: PaymentStrategy defines the contract — pay() and refund(). Every concrete implementation must provide both. The interface appears at the top of the hierarchy, with implementors below.

2. **Three realizations (..

   >):** CreditCardPayment, PayPalPayment, and CryptoPayment all implement PaymentStrategy. The dashed hollow arrow points toward the interface each class promises to fulfill.

3. Association ShoppingCart --> PaymentStrategy: The cart holds a reference to PaymentStrategy — not to any specific implementation. This navigability arrow (open head, not filled diamond) means ShoppingCart has a field of type PaymentStrategy. Crucially, it is typed to the interface, not a concrete class.
4. The power of this design: Because ShoppingCart depends on PaymentStrategy (the interface), you can call cart.setPayment(new CryptoPayment()) at runtime and the cart works without any changes to its own code. The class diagram makes this extensibility visible — and it shows exactly where the seam between context and strategy is.

Connection to practice: This is the same pattern behind Java’s Comparator, Python’s sort(key=...), and every payment SDK you will ever integrate in your career. Class diagrams let you see the shape of the pattern independent of any language.

5. Chapter Review & Spaced Practice

To lock this information into your long-term memory, do not skip this section!

Active Recall Challenge: Grab a blank piece of paper. Without looking at this chapter, try to draw the UML Class Diagram for the following scenario:

1. A School is composed of one or many Departments (If the school is destroyed, departments are destroyed).
2. A Department aggregates many Teachers (Teachers can exist without the department).
3. Teacher is a subclass of an Employee class.
4. The Employee class has a private attribute salary and a public method getDetails().

Review your drawing against the rules in sections 2 and 3. How did you do? Identifying your own gaps in knowledge is the most powerful step in the learning process!

6. Practice

Test your knowledge with these retrieval practice exercises. These diagrams are rendered dynamically to ensure you can recognize UML notation in any context.

Pedagogical Tip: If you find these challenging, it’s a good sign! Effortful retrieval is exactly what builds durable mental models. Try coming back to these tomorrow to benefit from spacing and interleaving.

7. Interactive Tutorials

Master UML class diagrams by writing code that matches target diagrams in our interactive tutorials:

• UML Class Diagrams in Python
• UML Class Diagrams in Java

Unlocking System Behavior with UML Sequence Diagrams

Introduction: The “Who, What, and When” of Systems

Imagine walking into a coffee shop. You place an order with the barista, the barista sends the ticket to the kitchen, the kitchen makes the coffee, and finally, the barista hands it to you. This entire process is a sequence of interactions happening over time.

In software engineering, we need a way to visualize these step-by-step interactions between different parts of a system. This is exactly what Unified Modeling Language (UML) Sequence Diagrams do. They show us who is talking to whom, what they are saying, and in what order.

Learning Objectives

By the end of this chapter, you will be able to:

1. Identify the core components of a sequence diagram: Lifelines and Messages.
2. Differentiate between synchronous, asynchronous, and return messages.
3. Model conditional logic using ALT and OPT fragments.
4. Model repetitive behavior using LOOP fragments.

Part 1: The Basics – Lifelines and Messages

To manage your cognitive load, we will start with just the two most fundamental building blocks: the entities communicating, and the communications themselves.

1. Lifelines (The “Who”)

A lifeline represents an individual participant in the interaction. It is drawn as a box at the top (with the participant’s name) and a dashed vertical line extending downwards. Time flows from top to bottom along this dashed line.

2. Messages (The “What”)

Messages are the communications between lifelines. They are drawn as horizontal arrows. UML 2 distinguishes three main arrow styles (sources: Fowler, UML Distilled, ch. 4; Rumbaugh, Jacobson & Booch, The Unified Modeling Language Reference Manual):

• Synchronous Message — solid line with filled (triangular) arrowhead. The sender blocks until the receiver responds, like calling a method and waiting for it to return.
• Asynchronous Message — solid line with open (stick) arrowhead. The sender fires the message and continues immediately, like posting an event to a queue or invoking a callback you don’t wait for.
• Return Message — dashed line with open arrowhead. Represents control (and often a value) returning to the original caller. Return arrows are optional in UML 2: include them when the returned value is important, omit them when a synchronous call obviously returns.

⚠ Common mistake: Students often confuse the filled vs. open arrowhead, treating both as synchronous. The rule: filled = blocks, open = fires-and-forgets. Remember it as “filled is full commitment; open lets go.”

Visualizing the Basics: A Simple ATM Login

Let’s look at the sequence of a user inserting a card into an ATM.

Notice the flow of time: Message 1 happens first, then 2, 3, and 4. The vertical dimension is strictly used to represent the passage of time.

Stop and Think (Retrieval Practice): If the ATM sent an alert to your phone about a login attempt but didn’t wait for you to reply before proceeding, what type of message arrow would represent that alert? (Think about your answer before reading on).

Part 1.5: Activation Bars and Object Naming

Now that you understand the basic elements, let’s add two important details that appear in real-world sequence diagrams.

Activation Bars (Execution Specifications)

An activation bar (also called an execution specification) is a thin rectangle drawn on a lifeline. It represents the period during which a participant is actively performing an action or behavior—for example, executing a method. Activation bars can be nested across software lifelines and within a single lifeline (e.g., when an object calls one of its own methods). Human actors are usually shown as initiators or recipients, not as executing software behavior, so they normally do not need activation bars.

The blue bars show when each object is actively processing. Notice how the Station is active from when it receives requestStop() until it sends the confirmation, and how the Train has separate execution bars for addStop(), openDoors(), and closeDoors().

Object Naming Convention

Lifelines in sequence diagrams represent specific object instances, not classes. The standard naming convention is:

objectName : ClassName

• If the specific object name matters:
• If only the class matters: (anonymous instance)
• Multiple instances of the same class get distinct names:

This is different from class diagrams, which show classes in general. Sequence diagrams show one particular scenario of interactions between concrete instances.

Consistency with Class Diagrams

When you draw both a class diagram and a sequence diagram for the same system, they must be consistent:

• Every message arrow in the sequence diagram must correspond to a method defined in the receiving object’s class (or a superclass).
• The method names, parameter types, and return types must match between the two diagrams.

Part 2: Adding Logic – Combined Fragments

Real-world systems rarely follow a single, straight path. Things go wrong, conditions change, and actions repeat. UML uses Combined Fragments to enclose portions of the sequence diagram and apply logic to them.

Fragments are drawn as large boxes surrounding the relevant messages, with a tag in the top-left corner declaring the type of logic, such as , , , or .

Common fragment syntax in sequence diagrams:

• Optional behavior:
• Alternatives with guarded branches:
• Repetition:
• Parallel branches:
• Early exit:
• Critical region:
• Interaction reference:

1. The OPT Fragment (Optional Behavior)

The opt fragment is equivalent to an if statement without an else. The messages inside the box only occur if a specific condition (called a guard) is true.

Scenario: A customer is buying an item. If they have a loyalty account, they receive a discount.

Notice the [hasLoyaltyAccount == true] text. This is the guard condition. If it evaluates to false, the sequence skips the entire box.

2. The ALT Fragment (Alternative Behaviors)

The alt fragment is equivalent to an if-else or switch statement. The box is divided by a dashed horizontal line. The sequence will execute only one of the divided sections based on which guard condition is true.

Scenario: Verifying a user’s password.

3. The LOOP Fragment (Repetitive Behavior)

The loop fragment represents a for or while loop. The messages inside the box are repeated as long as the guard condition remains true, or for a specified number of times.

Scenario: Pinging a server until it wakes up (maximum 3 times).

Part 3: Putting It All Together (Interleaved Practice)

To truly understand how these elements work, we must view them interacting in a complex system. Combining different concepts requires you to interleave your knowledge, which strengthens your mental model.

The Scenario: A Smart Home Alarm System

1. The user arms the system.
2. The system checks all windows.
3. It loops through every window.
4. If a window is open (ALT), it warns the user. Else, it locks it.
5. Optionally (OPT), if the user has SMS alerts on, it texts them.

Part 4: Combined Fragment Reference

The three fragments above (opt, alt, loop) are the most common, but UML defines additional fragment operators:

When to use ref: When a shared interaction (e.g., login, authentication, checkout) appears in many sequence diagrams, draw it once as its own diagram and reference it from others with a ref frame. This is the sequence-diagram equivalent of factoring out a function.

Part 5: From Code to Diagram

Translating between code and sequence diagrams is a critical skill. Let’s work through a progression of examples.

Example 1: Simple Method Calls

class Register {
    public void method(Sale sale, int cashTendered) {
        sale.makePayment(cashTendered);
    }
}

class Sale {
    public void makePayment(int amount) {
        Payment payment = new Payment(amount);
        payment.authorize();
    }
}

class Payment {
    Payment(int amount) { }

    void authorize() { }
}

class Payment {
public:
    explicit Payment(int amount) { }

    void authorize() { }
};

class Sale {
public:
    void makePayment(int amount) {
        Payment payment(amount);
        payment.authorize();
    }
};

class Register {
public:
    void method(Sale& sale, int cashTendered) {
        sale.makePayment(cashTendered);
    }
};

class Payment:
    def __init__(self, amount: int) -> None:
        pass

    def authorize(self) -> None:
        pass


class Sale:
    def make_payment(self, amount: int) -> None:
        payment = Payment(amount)
        payment.authorize()


class Register:
    def method(self, sale: Sale, cash_tendered: int) -> None:
        sale.make_payment(cash_tendered)

class Payment {
  constructor(amount: number) { }

  authorize(): void { }
}

class Sale {
  makePayment(amount: number): void {
    const payment = new Payment(amount);
    payment.authorize();
  }
}

class Register {
  method(sale: Sale, cashTendered: number): void {
    sale.makePayment(cashTendered);
  }
}

Notice how the Payment constructor call becomes a create message in the sequence diagram. The Payment object appears at the point in the timeline when it is created.

Example 2: Loops in Code and Diagrams

import java.util.List;

class Item {
    int getID() { return 0; }
}

class SaleLine {
    final String description;
    final int total;

    SaleLine(String description, int total) {
        this.description = description;
        this.total = total;
    }
}

class B {
    void makeNewSale() { }

    SaleLine enterItem(int itemId, int quantity) {
        return new SaleLine("", 0);
    }

    void endSale() { }
}

class A {
    private final List<Item> items;
    private int total;
    private String description = "";

    A(List<Item> items) {
        this.items = items;
    }

    public void noName(B b, int quantity) {
        b.makeNewSale();
        for (Item item : getItems()) {
            SaleLine line = b.enterItem(item.getID(), quantity);
            total = total + line.total;
            description = line.description;
        }
        b.endSale();
    }

    private List<Item> getItems() {
        return items;
    }
}

#include <string>
#include <vector>

class Item {
public:
    int getID() const { return 0; }
};

struct SaleLine {
    std::string description;
    int total;
};

class B {
public:
    void makeNewSale() { }

    SaleLine enterItem(int itemId, int quantity) {
        return {"", 0};
    }

    void endSale() { }
};

class A {
public:
    explicit A(std::vector<Item> items) : items(items) { }

    void noName(B& b, int quantity) {
        b.makeNewSale();
        for (const Item& item : getItems()) {
            SaleLine line = b.enterItem(item.getID(), quantity);
            total = total + line.total;
            description = line.description;
        }
        b.endSale();
    }

private:
    const std::vector<Item>& getItems() const {
        return items;
    }

    std::vector<Item> items;
    int total = 0;
    std::string description;
};

from dataclasses import dataclass


class Item:
    def get_id(self) -> int:
        return 0


@dataclass
class SaleLine:
    description: str
    total: int


class B:
    def make_new_sale(self) -> None:
        pass

    def enter_item(self, item_id: int, quantity: int) -> SaleLine:
        return SaleLine(description="", total=0)

    def end_sale(self) -> None:
        pass


class A:
    def __init__(self, items: list[Item]) -> None:
        self._items = items
        self._total = 0
        self._description = ""

    def no_name(self, b: B, quantity: int) -> None:
        b.make_new_sale()
        for item in self._get_items():
            line = b.enter_item(item.get_id(), quantity)
            self._total = self._total + line.total
            self._description = line.description
        b.end_sale()

    def _get_items(self) -> list[Item]:
        return self._items

class Item {
  getID(): number {
    return 0;
  }
}

type SaleLine = {
  description: string;
  total: number;
};

class B {
  makeNewSale(): void { }

  enterItem(itemId: number, quantity: number): SaleLine {
    return { description: "", total: 0 };
  }

  endSale(): void { }
}

class A {
  private total = 0;
  private description = "";

  constructor(private readonly items: Item[]) { }

  noName(b: B, quantity: number): void {
    b.makeNewSale();
    for (const item of this.getItems()) {
      const line = b.enterItem(item.getID(), quantity);
      this.total = this.total + line.total;
      this.description = line.description;
    }
    b.endSale();
  }

  private getItems(): Item[] {
    return this.items;
  }
}

The for loop in code maps directly to a loop fragment. The guard condition [more items] is a Boolean expression that describes when the loop continues.

Example 3: Alt Fragment to Code

Given this sequence diagram:

Equivalent code in four languages:

class A {
    private final B b;
    private final C c;

    A(B b, C c) {
        this.b = b;
        this.c = c;
    }

    public void doX(int x) {
        if (x < 10) {
            b.calculate();
        } else {
            c.calculate();
        }
    }
}

class B {
    void calculate() { }
}

class C {
    void calculate() { }
}

class B {
public:
    void calculate() { }
};

class C {
public:
    void calculate() { }
};

class A {
public:
    A(B& b, C& c) : b(b), c(c) { }

    void doX(int x) {
        if (x < 10) {
            b.calculate();
        } else {
            c.calculate();
        }
    }

private:
    B& b;
    C& c;
};

class B:
    def calculate(self) -> None:
        pass


class C:
    def calculate(self) -> None:
        pass


class A:
    def __init__(self, b: B, c: C) -> None:
        self._b = b
        self._c = c

    def do_x(self, x: int) -> None:
        if x < 10:
            self._b.calculate()
        else:
            self._c.calculate()

class B {
  calculate(): void { }
}

class C {
  calculate(): void { }
}

class A {
  constructor(
    private readonly b: B,
    private readonly c: C,
  ) { }

  doX(x: number): void {
    if (x < 10) {
      this.b.calculate();
    } else {
      this.c.calculate();
    }
  }
}

Quick Check (Generation): Try translating this code into a sequence diagram before checking the answer:

public class OrderProcessor {
    public void process(Order order, Inventory inv) {
        if (inv.checkStock(order.getItemId())) {
            inv.reserve(order.getItemId());
            order.confirm();
        } else {
            order.reject("Out of stock");
        }
    }
}

Reveal Answer

Real-World Examples

These examples show sequence diagrams for real systems. For each diagram, trace through the arrows top-to-bottom and narrate what is happening before reading the walkthrough.

Example 1: Google Sign-In — OAuth2 Login Flow

Scenario: When you click “Sign in with Google”, three systems exchange a precise sequence of messages. This diagram shows that flow — it illustrates how return messages carry data back and why the ordering of messages matters.

What the UML notation captures:

1. Three lifelines, one flow: Browser, AppBackend, and GoogleOAuth are the three participants. The browser intermediates between your app and Google — this is why OAuth feels like a redirect chain.
2. Solid arrows (synchronous calls): Every -> means the sender blocks and waits for a response before continuing. The browser sends a request and waits for the redirect before proceeding.
3. Dashed arrows (return messages): The --> arrows carry responses back — the auth code, the access token, the session cookie. Return messages always flow back to the caller.
4. Top-to-bottom = time: Reading vertically, you reconstruct the complete OAuth handshake in order. Swapping any two messages would break the protocol — the diagram makes those ordering dependencies visible.

Example 2: DoorDash — Placing a Food Order

Scenario: When a user submits an order, the app charges their card and notifies the restaurant. But what if the payment fails? This diagram uses an alt fragment to model both the success and failure paths explicitly.

What the UML notation captures:

1. Charge once, then branch on the response: The charge() call is issued before the alt fragment, and chargeResult is returned to OrderService. The alt then branches on the content of that response — never call payment twice. Putting the charge() inside both branches would imply a double charge attempt, which would be an architectural bug.
2. alt fragment (if/else): The dashed horizontal line inside the box divides the two branches. Only one branch executes at runtime. When you see alt, think if/else.
3. Guard conditions in [ ]: [chargeResult.approved] and [chargeResult.declined] are boolean guards — they must be mutually exclusive so exactly one branch fires.
4. Different paths, different participants: In the success branch, the flow continues to Restaurant. In the failure branch, it returns immediately to the app. The diagram makes both paths equally visible — no “happy path bias”.
5. Why alt and not opt? An opt fragment has only one branch (if, no else). Because we have two explicit outcomes — success and failure — alt is the correct choice.

Example 3: GitHub Actions — CI/CD Pipeline Trigger

Scenario: A developer pushes code, GitHub triggers a build, tests run, and deployment happens only if tests pass. This diagram uses opt for conditional deployment and a self-call for internal processing.

What the UML notation captures:

1. Self-call (build -> build): A message from a lifeline back to itself models an internal call — BuildService running its own test suite. The arrow loops back to the same column.
2. opt fragment (if, no else): Deployment only happens if all tests pass. There is no “else” branch — on failure the flow skips the opt block and continues to the notification.
3. Return after the fragment: gh --> dev: notify(testResults) executes regardless of whether deployment occurred — it is outside the opt box, at the outer sequence level.
4. Activation ordering: build runs runTests() before returning testResults to gh. Top-to-bottom ordering guarantees tests complete before GitHub is notified.

Example 4: Uber — Real-Time Driver Matching

Scenario: When a rider requests a trip, the matching service offers the ride to drivers until one accepts. This diagram shows a loop fragment combined with an alt inside — the most powerful combination in sequence diagrams.

What the UML notation captures:

1. loop fragment: The matching service repeats the offer-cycle until a driver accepts (the loop guard [no driver has accepted] checks the response). loop models iteration — equivalent to a while loop. In practice this loop also has a timeout (e.g., a maximum number of attempts before cancellation), which would tighten the guard condition.
2. Offer once per iteration, branch on the response: The diagram shows a single offerRide(request) per loop iteration — the driver’s response is either accepted or declined/timeout. The loop guard then decides whether to continue. Sending the same offer twice inside an alt would mistakenly model two separate offers for what is really one driver interaction.
3. Flow continues after the loop: Once a driver accepts, the loop guard becomes false and execution exits, then the notification is sent. Messages outside a fragment are unconditional.
4. DriverApp as a participant: The driver’s mobile app is a first-class lifeline. This shows that sequence diagrams can include mobile clients, web clients, and backend services on equal footing.

Example 5: Slack — Real-Time Message Delivery

Scenario: When you send a Slack message, it is persisted, then broadcast to all subscribers of that channel. This diagram shows the fan-out delivery pattern using a loop fragment.

What the UML notation captures:

1. Sequence before the loop: persist and get messageId happen exactly once — before the broadcast. The diagram makes this ordering explicit: a message is saved before it is delivered to anyone.
2. loop for fan-out delivery: Each online subscriber receives their own delivery. The lifeline subscriber : SlackClient[*] represents the set of recipient clients (distinct from the original sender); the asynchronous arrow ->> shows the gateway pushes the message — this is server-pushed, not a return value. In a channel with 200 members, the loop body executes 200 times.
3. ack after the loop: The original sender receives their acknowledgment (ack(messageId)) only after the broadcast completes. This is outside the loop — it is unconditional and happens once. Note that ack returns to sender, while delivery flows to subscriber — distinguishing these two lifelines is essential to model fan-out correctly.
4. WebSocketGateway as the central hub: All messages flow in and out through the gateway. The diagram shows this hub topology clearly — every arrow touches ws, revealing it as the architectural bottleneck. This is a useful architectural insight visible only in the sequence diagram.

Chapter Summary

Sequence diagrams are a powerful tool to understand the dynamic, time-based behavior of a system.

• Lifelines and Messages establish the basic timeline of communication.
• OPT fragments handle “maybe” scenarios (if).
• ALT fragments handle “either/or” scenarios (if/else).
• LOOP fragments handle repetitive scenarios (while/for).

By mastering these fragments, you can model nearly any procedural logic within an object-oriented system before writing a single line of code.

End of Chapter Exercises (Retrieval Practice)

To solidify your learning, attempt these questions without looking back at the text.

1. What is the key difference between an ALT fragment and an OPT fragment?
2. If you needed to model a user trying to enter a password 3 times before being locked out, which fragment would you use as the outer box, and which fragment would you use inside it?
3. Draw a simple sequence diagram (using pen and paper) of yourself ordering a book online. Include one OPT fragment representing applying a promo code.

Practice

Test your knowledge with these retrieval practice exercises. These diagrams are rendered dynamically to ensure you can recognize UML notation in any context.