UML and system modelling: seven views of one system.

Why we model: selective abstraction as engineering tool.

Software engineering is the discipline that builds large, useful programs without their complexity becoming the dominant cost. Modelling is one of the levers that keeps complexity under control: a model shows part of the system clearly precisely because it hides everything else. Different stakeholders need to see different parts, which is why there is no single diagram type that captures a system, and why this companion treats seven of them.

The idea of a "model" in engineering predates software. In mechanical, civil, and electrical engineering, drawings replace prose because they are denser, more checkable, and (when standardised) less ambiguous. The same case applies to software, with one extra wrinkle: the artefact we are modelling does not yet exist, so the model has to do double duty as both description (of what we intend to build) and specification (of what counts as having built it correctly). Sommerville (Software Engineering, 10th ed., 2015, ch.5) captures this in a one-sentence definition that is worth taking apart:

Two words in that sentence carry the weight: ignores and complementary. A model ignores by design; if it captured every detail, it would be the system itself, and would offer no leverage. And no single model is enough: a use case diagram says nothing about how data is structured, a class diagram says nothing about how messages flow over time, a sequence diagram says nothing about how the system is deployed across machines. Complementary models compose into a full picture because each ignores something different, and the engineer's job is to know which complement to add next.

The shorter, practitioner-facing summary is: a model is the language of the designer; a description of the system-to-be-built (or as-built) from a particular perspective; a tool for communicating with stakeholders; and a means of reasoning about some characteristic of the system without holding the whole of it in your head. UML, the Unified Modelling Language, is the standardised vocabulary in which those models are now drawn. The rest of this chapter develops where UML came from (§2), where it is used in practice (§3), how to choose which model to draw (§4 through §6), and how to draw each of the seven course diagrams correctly (§7 through §13). Section 14 ties them together with a worked example from elicitation to first-cut design; section 15 lists the marking pitfalls.

Two questions a model must answer

Before you draw a model, you should know which two questions it answers, because if it answers neither, it is not earning its place on the page:

• Who is the reader? A developer? An auditor? A clinical specialist? The customer's contracting officer? A model is a piece of communication; it has to be addressed to someone.
• What decision does it support? Scope confirmation? An algorithm choice? A staffing estimate? A deployment topology? A model that does not help anyone decide anything is decoration.

Every diagram in this companion is paired with a short "where it earns its place" panel that names the reader and the decision. Keep those two anchors in mind as you read; they are what separates a useful diagram from a textbook one.

Three modelling moves

Underneath the fourteen UML diagram types are just three modelling moves you make again and again. Recognising which move you are making is the easiest way to pick the right diagram:

• Abstraction. Strip out detail to expose structure. The class diagram does this for code; the use case diagram does it for usage; the deployment diagram does it for infrastructure.
• Decomposition. Split one thing into parts that can be reasoned about separately. Composite use cases decompose system functionality; activity diagrams decompose a use case into ordered steps; component diagrams decompose the system into modules.
• Refinement. Take a sketched-in object and add detail. A use case sketch refines into an activity diagram; a class diagram refines into a sequence diagram; a state name refines into a sub-state machine.

If you find yourself drawing a diagram without doing one of these three moves, the diagram is probably not adding value; you are decorating.

A model earns its place by what it makes discussable. A use case diagram makes the system's interactions with its users discussable in a single page; a class diagram makes its static structure discussable; a sequence diagram makes one specific interaction discussable. None of them captures the system, and that is exactly the point.

The Three Amigos and the method wars.

UML did not arrive whole. It was the result of a deliberate, three-year unification at Rational Software (1994 to 1997) of three competing object-oriented modelling notations, led by the engineers who had created them. Understanding that backstory matters, because every UML diagram type still bears the fingerprint of which of the three contributed it.

Before UML: the method wars

The 1980s and early 1990s were the boom years of object-oriented analysis and design. Smalltalk had been released in 1980; C++ in 1985; Java arrived in 1995. As industry adopted these languages, the demand for diagrammatic notations to plan large object-oriented systems exploded. By the early 1990s the field had no fewer than fifty published methods, each with its own conventions for classes, associations, inheritance, and behaviour. Fowler later called the period the "method wars" (UML Distilled, 2003, ch.1): teams that adopted one method could not exchange diagrams with teams that adopted another, and reading the OO literature meant learning a different graphical vocabulary every few months.

Three of the methods dominated by 1994. Each was associated with one prominent author, each came out of a different industrial setting, and each was strongest in a different part of the lifecycle:

The three were complementary in scope (analysis, design, requirements) and convergent in spirit (all object-oriented, all diagrammatic), but stubbornly incompatible in notation. A class drawn in OMT looked nothing like a class drawn in Booch, and Jacobson's use case bubbles had no equivalent in either. Teams that mixed methods spent disproportionate effort translating between them.

The unification: 1994 to 1997

The first move came in October 1994: Rumbaugh left General Electric to join Booch at Rational Software, with the explicit goal of merging OMT and the Booch method. They circulated a draft "Unified Method" version 0.8 in October 1995. Jacobson sold Objectory to Rational the same month and joined the team; from that point the three were collaborating in one company, on one notation. Industry shorthand quickly named them the Three Amigos, after the 1986 film.

The unification was not a vote between three favourites; it was a re-engineering of the combined notation around what each method did best. Rumbaugh's class-and-association notation became UML's structural backbone; Jacobson's use cases were lifted in essentially unchanged; Booch's emphasis on design-level diagrams supplied component and deployment views. The result was published as UML 0.9 in June 1996, renamed Unified Modelling Language rather than Unified Method (a deliberate distinction: a language is a notation only, not a prescribed process).

In November 1997, the Object Management Group (OMG) adopted UML 1.1 as a standard. The OMG is an industry consortium founded in 1989 to standardise object-oriented and distributed-system technologies (it also maintains CORBA and SysML). UML's transfer to OMG was the moment it stopped being a Rational product and became a public standard. Major revisions since:

The OMG specification runs to several hundred pages and is the authoritative reference when a notation question is genuinely contested. For day-to-day use, Fowler's UML Distilled (3rd ed., Addison-Wesley, 2003) remains the most-cited compact practitioner reference; the "three amigos" themselves jointly published The Unified Modeling Language User Guide (2nd ed., 2005) as the official user-level companion.

UML is a language, not a method

A common confusion is to expect UML to tell you when to draw each diagram. It does not. UML is a notation only: it standardises the shape of an ellipse for a use case, the rules for an include arrow, the compartments of a class box. The decisions about which diagrams to draw, in what order, and how much detail to put on them belong to the process, which is a separate concern. The most-cited process built around UML is the Rational Unified Process (RUP, Kruchten, 2003), but agile teams routinely use a small subset of UML inside Scrum or XP without adopting RUP at all. The course's structure follows this separation: chapter 3 covers the process by which requirements are produced; this chapter covers the language in which the resulting models are drawn.

Where UML lives now.

UML's status today is uneven across the industry. Knowing where it is heavily used and where it is light-touch is part of using it correctly.

Heavily used. Regulated domains (medical devices, automotive safety, avionics, rail), where traceability from requirements to design is a certification requirement; Model-Based Systems Engineering (MBSE), where SysML (a UML profile) is the primary modelling notation; teaching, where UML's diagrammatic vocabulary is still the standard way to introduce object-oriented design; and large enterprise architecture work, where component and deployment diagrams remain the standard medium for documenting system structure.

Lighter use. Agile teams often use only a subset (use cases or activity diagrams for requirements; class diagrams sketched on whiteboards) and rarely produce the full UML model that the textbook describes. The reasons are pragmatic, not ideological: keeping a heavyweight model in sync with rapidly changing code is expensive, and teams have learned to invest in the diagrams that pay back in conversation rather than those that pay back in documentation.

Areas of growth. The rise of safety- and security-critical AI systems has brought renewed interest in MBSE and formal modelling, including UML-derived notations. The diagrammatic vocabulary has also re-emerged in domain-specific contexts (database modelling tools, infrastructure-as-code visualisers, sequence diagrams generated automatically from distributed traces).

For the COMP433 student, the practical takeaway is that the seven diagrams treated in depth here are all in current use somewhere, and being fluent in them is genuinely portable knowledge. The diagrams treated more briefly (object, communication, timing, interaction overview) are still in the standard but are encountered much less often in industry.

The four families of models.

Sommerville (2015, ch.5) groups system models into four families by what they make discussable. The families are not mutually exclusive (one diagram can belong to two), but knowing the family helps decide what kind of question the diagram is being drawn to answer, and which UML diagram types are the natural fit. Hover any card below for a worked example and a sharper definition.

The families are not partitions. A use case diagram is partly context and partly interaction; an activity diagram can be either interaction or behavioural depending on the level it is drawn at; a component diagram is structural but its interface contracts already imply interaction. The classification is a thinking aid, not a rigid taxonomy: when a team realises it has drawn three interaction diagrams and no structural one, it has a signal that an important class diagram is still missing.

From elicitation to deployment: where each model fits.

The diagrams in this chapter do not exist in isolation. Each one sits at a particular point in the software lifecycle, takes its input from the artefact that precedes it, and produces an output that the next artefact builds on. This section is the map that the rest of the companion fills in.

A common misconception is that UML diagrams are alternatives ("should I draw a use case or a class diagram?"). The right framing is sequential: each diagram answers a question the previous one raised, at the right level of abstraction for the stage you are in. Knowing which question is on the table is what tells you which diagram to draw next.

Reading the pipeline

Three observations worth pausing on:

1. Cost estimation is a decision gate, not a deliverable. Steps 1 and 2 produce the requirements; step 3 prices them. The estimate is what the customer needs to authorise the design work (steps 4–10). Doing the estimate too early, before requirements are stable, produces a number nobody can defend. Doing it too late, after design has started, means the team is committed to a price that may not match the work.
2. The arrows go forward but the work goes back and forward. A class diagram drawn at step 6 usually exposes a missing requirement at step 2, which is added and propagates back through the use cases (step 4). The pipeline is a thinking aid, not a waterfall.
3. Not every step is mandatory. A small project may skip the activity diagram entirely; a project with no domain objects with lifecycles may skip the state machine. The skip rule is the same as the model rule: if it does not change anyone's decision, do not draw it.

Cost estimation in context

Cost estimation is treated in depth in the Ch.3 companion, which includes an interactive calculator. The view from this chapter is about when and why, not how. The key implications:

• What you estimate. The unit of estimation is the User Requirement, not the use case. A single user requirement may map to several use cases (or none); the estimate has to attach to the requirement so it survives the design pass.
• What the estimate produces. Total effort (in person-weeks), schedule (effort × 1.30 buffer), cost (schedule × weekly salary), and a quoted price range (cost × 1.10 to 1.30). That price range is the artefact that goes back to the customer for sign-off.
• What changes the estimate. Anything that changes the requirements. A new UR added during use case modelling does not enter the pipeline silently; it goes back to step 3 and the estimate is revised. This is why the iteration loop in the figure points back to step 1 and not to step 2 or 3 alone.
• What the estimate does not do. It does not constrain how the team builds the system, which design patterns it uses, or which architectural style fits. Those are downstream choices that the estimate's coarseness has to absorb.

A worked thread through the journey

To make the pipeline concrete, follow one user requirement through it. The example is the Library System used as the running example in the rest of this companion:

One user requirement, ten artefacts. Most of the value is not in any single artefact; it is in the traceability from UR3 to the deployment node, which is what lets the team change the design and know which other artefacts to update. The rest of this companion is the toolkit for producing the entries in column two correctly.

UML 2.5: fourteen diagram types.

The UML 2.5 specification defines fourteen diagram types, split into structural (seven) and behavioural (seven). Nine of these are conventionally treated as the "standard" set you will encounter on real projects, and seven are covered in depth in this companion (and used in the COMP433 project). The map below lists all fourteen for completeness; the italicised types are part of the standard but encountered less often in practice.

The seven types covered in depth below are: use case, activity, class, sequence, state machine, component, and deployment. Together they cover the full life cycle of a typical project: requirements (use case, activity), analysis and design (class, sequence, state machine), and architecture (component, deployment).

Use case diagrams: actors, tasks, system boundary.

A use case diagram is a one-page picture of who interacts with the system and the named tasks they perform. It is the first UML diagram drawn on most projects: it converts the list of User Requirements into something that fits on one A4 page, makes scope confirmable with the customer, and produces the index of tasks that downstream diagrams (activity, sequence, class) refine.

What a use case diagram is for, precisely

The diagram serves three decisions, and only three:

• Scope confirmation. The customer signs off (or contests) that the listed use cases are the right set and that no major task is missing. The diagram is read from the actor side: "as a BookBorrower, the system lets me Borrow, Return, Renew, and Browse; is that all I need it to do?".
• Actor inventory. Names the principal and secondary actors that interact with the system. This list flows directly into requirements (each actor needs its sentence-long description) and into design (each actor becomes a class or external system in the class diagram).
• Task index. Names the tasks (use cases). Each use case will get its own textual description (section 8), at least one activity diagram if the workflow is non-trivial (section 9), and at least one sequence diagram for its key scenario (section 11). The diagram is the table of contents for those downstream artefacts.

It does not show: the order of work inside a use case (use an activity diagram), the messages between objects realising a use case (use a sequence diagram), what data the system holds (use a class diagram), or where the system runs (use a deployment diagram). A use case ellipse is, deliberately, an opaque label; the substance lives in the textual description.

When the diagram is drawn

In the project pipeline (section 5, figure 1), the use case diagram is the bridge between requirements and design. It is drawn for the Phase 2 deliverable: each User Requirement that names a clear actor and a clear goal becomes one use case, and the diagram makes the relationships between them (sub-tasks, conditional alternatives) visible alongside the textual UR / SR list. It is then revised at the start of Phase 3 as design begins, because the design pass surfaces additional sub-tasks (which become <<include>> use cases) and alternative paths (which become <<extend>> use cases).

Building blocks

A use case diagram has three building blocks: actors, use cases, and the system boundary. Actors are drawn as stick figures (or sometimes labelled boxes for non-human actors) outside the boundary; use cases are ellipses with a verb-phrase label inside the boundary; the system boundary is a rectangle that contains the use cases and explicitly excludes the actors. Associations are simple solid lines between an actor and a use case they participate in (no arrow head, because participation is undirected). Refinement relationships between use cases are drawn as dashed arrows with one of three stereotypes: <<include>>, <<extend>>, or generalisation (inheritance).

Building blocks, drawn correctly

Actors: principal and secondary

An actor is a role someone or something plays when interacting with the system. Actors are not specific people; the same person can be two actors at different times. A doctor who also borrows books at the staff library is a Doctor in one system and a BookBorrower in the other. The course conventionally splits actors into two kinds:

• Principal actor. The user who initiates or benefits from a use case. Usually a human role (BookBorrower, Librarian, Doctor, Nurse).
• Secondary actor. An external system, hardware device, or system-triggered event that the system depends on or interacts with. Common examples: SystemTimer (for scheduled events), EmailSystem (an external service the system pushes to), BankSystem (an external payment service the system queries).

How to identify actors:

• What roles do the direct users of the system play?
• Who provides information to the system?
• Who receives information from the system?
• What external systems must the system communicate with?

Notation convention. Each actor's name is a noun (CamelCase, no spaces), and the actor is documented in one sentence covering its role and how it interacts with the system. For example: "BookBorrower: a member of the library who borrows physical copies of books (Principal)." The description belongs in the requirements document next to the diagram; the diagram itself only carries the name.

Use cases: things actors do with the system

A use case is a task an actor needs to perform with the help of the system. Two rules from the course notes:

• Always start a use case label with a verb. "Borrow copy of a book", not "Book borrowing". The verb is what tells you it is a use case rather than a class.
• Describe the use case's semantics in a sentence or two. The ellipse on the diagram is the entry point; the description in the requirements document is what the team builds against.

How to find use cases:

• Scenario-based analysis. Write the system's processes as scenarios; each interaction in a scenario is a candidate use case.
• Actor-based analysis. Start from the actor list; for each actor, ask what they need from the system, and what other interactions they take part in for someone else's benefit.

Relationships between use cases: include, extend, generalisation

Once you have more than a handful of use cases, you will start to see that some use cases share sub-tasks with each other, others fire only in exceptional circumstances, and others are variations on a common theme. UML 2.5 gives three stereotypes for these refinements. Each has a precise meaning and a precise arrow direction, and confusing them is the single most common notation error on this material.

Worked second example: ATM cash withdrawal

The Library example shows the mechanics; an ATM example shows when the stereotypes pay back in a different domain.

• Withdraw cash is the primary use case (initiated by Cardholder).
• Authenticate customer is <<include>>-d from Withdraw cash (and from every other transactional use case: Deposit, Transfer, Check balance). It is factored out because the authentication policy will change later (PIN, biometric, multi-factor) and all five base use cases must change together.
• Print receipt is <<extend>>-ed from Withdraw cash, at the extension point "after dispensing cash", with guard [customer chose receipt]. Most withdrawals do not print a receipt; the extension exists to keep the Withdraw description clean.
• Refuse transaction is <<extend>>-ed from Withdraw cash, at the extension point "after balance check", with guard [insufficient funds]. This is structurally identical to the Library's Refuse loan, and demonstrates that the same pattern recurs across very different domains.

The teaching point: <<include>> exists to avoid duplication when two or more base use cases share a sub-task (Authenticate customer is shared by Withdraw, Deposit, Transfer, and Check balance). <<extend>> exists to keep the base description clean when an optional or exceptional behaviour would otherwise crowd it (Print receipt and Refuse transaction only run sometimes; they belong on a separate ellipse, not as a footnote inside Withdraw).

Extension points

A common question is "where in the base does the extension fire?" The answer is given by an extension point: a named position in the base's workflow, declared inside the base ellipse (in a third compartment) or in the base's textual description. Borrow copy of a book typically declares two extension points:

• maxItemsCheck, located after the system has counted the borrower's current loans. The Refuse loan extension fires here with guard [items on loan == 6].
• identityValidation, located after the BookBorrower's identity has been confirmed. A separate extension (say, RequireGuardian) might fire here with guard [member is minor].

Extension points keep the base's flow auditable: a reader of the base description sees the named hooks and can look up which extensions attach to each. Without them, an <<extend>> arrow is just "this fires somewhere in here", which is too vague to be useful in a contract.

When NOT to use these refinements

A diagram with more refinement arrows than associations is over-modelled. Three signs that you are overusing the stereotypes:

• An <<include>> with one parent. If only one use case includes a particular sub-task, the sub-task is not being reused; it is being prematurely factored. Inline it into the description.
• An <<extend>> with no extension point. Without a named extension point, the extension is just an alternative path of the base. Document it as an alternative scenario in the base's description (section 8) rather than as a separate ellipse.
• Generalisation between use cases that share no actor. Use case generalisation rarely earns its place in business systems; it is more useful in tooling that auto-generates code from the model. For COMP433 projects, prefer <<include>> for shared sub-tasks and <<extend>> for variants, and reach for generalisation only when the two are genuinely the same use case at different specificity levels.

Multi-level (composite) use cases

For larger systems, a single top-level diagram becomes unreadable. The standard pattern is to draw a high-level diagram with composite use cases (each one labelled with a verb phrase like "Manage patient registration"), and to draw a separate first-level diagram for each composite that decomposes it into its constituent use cases. A second-level diagram may decompose a particular first-level use case further, if needed.

For the Mentcare system (the same running example as in Ch.3), this is the pattern used in the course: the top-level diagram shows "Manage patient registration", "Manage patient medical record", "Generate reports", and "View patient info". The "Generate reports" composite is then expanded in a first-level diagram with sub-cases like "Generate admitted patient report" and "Generate discharged patient reports". Treat the top-level diagram as a map of the system, and each first-level diagram as a magnified region of that map.

Use case descriptions: the diagram is the index.

A use case ellipse on a diagram is barely a label. The use case itself is fully specified in a structured description. This is the same template the requirements companion uses in Section 8; here it is applied to use cases specifically.

The fields are: System Name, Use Case Title, Description, Actors, Data, Stimulus/Trigger, Pre-conditions, Workflow (or Sequence/Flow of Events), Post-conditions/Response, Comments. Below is the course's canonical worked example.

Scenarios: normal, alternative, error

Each time an actor interacts with the system, the triggered use case instantiates a scenario: a specific path through the use case with no branching. Scenarios are typically documented as text alongside the diagram and serve as the readable narratives that customers and testers can confirm against. For each non-trivial use case, the course expects at least three scenarios:

• Normal scenario. The happy path that completes successfully under the typical conditions.
• Alternative scenario. An equally successful but different path (a different actor, a different starting state, a non-default flow).
• Error scenario. An unsuccessful outcome with explicit handling. What happens when the pre-condition fails, when the network drops, when the data is missing.

Worked scenarios for "Borrow copy of a book":

Notice that the two error scenarios describe quite different failures: one is a business rule violation (too many books), the other is a physical/data integrity issue (damaged barcode). Both are equally valid sources of requirements: the first generates "the system shall enforce a maximum of six items on loan"; the second generates "the system shall provide a manual barcode entry option".

Activity diagrams: flow, decisions, parallelism.

An activity diagram captures the workflow of a use case or a business process. It is the right diagram when the team needs to talk about the order of work, the decisions that branch the flow, and the activities that can run in parallel.

Activity diagrams have a small, fixed vocabulary. Once the symbols are known, the diagram reads like a flow chart with two added powers: it can show parallelism explicitly, and it can assign activities to actors using swimlanes.

Notation

When to draw an activity diagram

Activity diagrams pay back when the workflow has at least one of: a non-trivial number of decisions, parallel work that the team needs to discuss explicitly, or coordination across multiple actors. They are over-engineering for use cases with a single linear path of three or four steps.

Two practical conventions:

• One activity diagram per use case is the typical granularity. Higher-level activity diagrams (business-process view) are also common, but mixing the two granularities in one diagram makes both hard to read.
• Swimlanes are worth the effort as soon as more than one actor is involved. The same activities, drawn without swimlanes, lose the information about who does what.

Class diagrams: the system's static structure.

A class diagram shows the classes in a system and the associations between them. It is the longest-lived diagram on most projects, because the static structure changes more slowly than any particular flow through it.

Anatomy of a class box

Visibility, in full

UML's visibility markers map directly to access modifiers in mainstream OO languages, with one or two extra options:

• + public: accessible by any client of the class.
• - private: accessible only by members of the same class.
• # protected: accessible by members of the class or any subclass.
• ~ package: accessible by classes in the same package.
• / derived: a value computed from other attributes, not stored independently (e.g., /age computed from birthDate).

Relationships: associations, generalisation, aggregation

Multiplicity, in detail

Multiplicity on an association end answers: how many instances of this class can participate in the relationship at one time? Standard values:

Aggregation vs composition

Both denote "part of" relationships, but with different lifetime semantics:

• Aggregation (open diamond): a "weak" part-of. The part can exist independently of the whole. A team has members; if the team is dissolved, the members still exist. Aggregation is a hint about intent more than a binding constraint.
• Composition (filled diamond): a "strong" part-of. The part's lifetime is tied to the whole. If the whole is destroyed, so are the parts. A house has rooms; destroy the house and the rooms cease to exist.

Modern style is to avoid aggregation where composition would do, because aggregation is semantically weak: most tools and reviewers cannot distinguish it from a plain association. Composition, by contrast, has bite.

Association classes

When an association itself has attributes that do not belong to either of the connected classes, those attributes live on an association class. Example: a Loan between a LibraryMember and a BookCopy has its own startDate and returnDate; these are attributes of the borrowing relationship, not of the member or of the copy. The association class is drawn as a regular class box, connected to the association line by a dashed link.

Data-driven noun-verb analysis

The standard recipe, introduced by Shlaer and Mellor in the late 1980s and used in the course, is the noun-verb analysis: read through the requirements document and underline every noun phrase; collect those noun phrases as a candidate class list; discard inappropriate ones (redundant, omnipotent, vague, meta-language, outside the system scope, or really attributes of something else); then identify every verb and assign verbs to candidate classes as operations. The result is a first-cut class diagram that is grounded in the requirements you wrote, rather than the developer's imagination.

Six categories of "inappropriate" noun, worth memorising because they recur in reviews of analysis-level class lists:

• Redundant. Two nouns name the same thing (e.g., "library member" and "borrower" both refer to LibraryMember).
• Omnipotent / "manager" / "system". Vague catch-alls that would do everything; usually a sign the analyst stopped abstracting too early.
• Vague. "Information", "data", "item"; not concrete enough to model.
• Meta-language. Words about the requirements rather than the domain ("requirement", "feature", "constraint").
• Outside the system scope. Real things, but the system does not need to know about them.
• Actually attributes. "Title" and "ISBN" sound like classes but are attributes of Book.

Heuristic categories from Booch's Object-Oriented Analysis and Design for which nouns make good classes:

• Tangible or real-world things (book, copy, course, room).
• Roles (library member, student, doctor, member of staff).
• Events (arrival, departure, request, payment).
• Interactions (meeting, consultation, treatment).

What makes a good analysis class

Five criteria, drawn from Cooper, Larman, and the broader OO design literature, that practitioner reviews look for:

• Its name reflects its intent. "AccountManager" tells you what it does; "Util" or "Helper" tells you nothing.
• It is a crisp abstraction. Models one specific element of the problem domain, not several.
• A small, defined set of responsibilities. One reason to change; one cluster of behaviour.
• High cohesion. Its attributes and operations are tightly related.
• Low coupling. Few necessary associations with other classes; nothing accidental.

Sequence diagrams: the order of messages.

A sequence diagram shows one specific interaction: who sends what message to whom, in what order. Time runs top to bottom; participants are arranged left to right. Unlike a class diagram, which captures the system at rest, a sequence diagram captures the system in motion.

Notation

• Lifelines: vertical dashed lines representing participants. Drawn from a participant box at the top.
• Activations: thin rectangles on a lifeline showing when a participant is active (processing).
• Messages: horizontal arrows between lifelines. Solid arrow = synchronous call. Dashed arrow with open arrowhead = return. Open arrowhead (no shaft) = asynchronous message.
• Fragments (UML 2.0): boxed regions with an operator label (alt, opt, loop, par, ref) that contain conditional or repeating behaviour.

UML 2.0 fragments, in detail

UML 2.0 added interaction fragments to make sequence diagrams expressive enough for non-trivial flows. The five most common operators:

Step through a sequence diagram

The interactive below plays a sequence diagram one message at a time. Use it to see how activation bars grow and shrink as messages flow.

State machine diagrams: the object's life.

A state machine diagram captures the states an object passes through during its lifetime and the events that cause transitions between them. It is the right diagram whenever a class has a meaningful "current state" that callers must reason about.

Notation

• States: rounded rectangles with the state name.
• Initial state: filled black circle, exactly one per diagram.
• Final state: filled black circle inside a ring.
• Transitions: labelled arrows between states, labelled event [guard] / action. Any of the three parts can be omitted.
• Internal activities: written inside the state box, with the form entry / action, do / action, exit / action.
• Composite states: a state that itself contains other states (sub-states). Drawn as a state box with internal states inside it.

When to draw a state machine

State machines pay back when at least one of the following is true:

• The class has more than two meaningful states and the transitions between them are non-trivial.
• The behaviour of the class depends on its current state (the same method does different things in different states).
• Errors and unexpected events have meaningful state-dependent behaviour.
• The state machine corresponds to a real, externally observable lifecycle (loan status, order status, ticket status).

Most classes do not need a state machine. Data carriers, value objects, and pure functions have no state in this sense. Drawing a state machine for them is over-engineering. Conversely, every domain object whose lifecycle is meaningful (Order, Loan, Ticket, Patient, Account) is a candidate.

Simulate the BookCopy state machine

The interactive below runs the BookCopy state machine. Fire events with the buttons and watch the current state change, with guards enforced.

Architectural diagrams: components and deployment.

Component and deployment diagrams sit higher up the abstraction ladder than the diagrams above. They are concerned with how the system is partitioned at build time and how it is distributed at run time.

Component diagrams

A component diagram shows the structural relationships between the major components of a system. A component in UML 2 is a modular part of the system with well-defined interfaces. Components offer two kinds of interface:

• Provided interfaces (drawn as a lollipop): operations the component makes available to clients.
• Required interfaces (drawn as a socket): operations the component needs from other components.

A provided lollipop fits into a matching required socket; the connection is valid if the socket's required operations are a subset of the lollipop's provided operations and their signatures are compatible.

Componentisation guidelines

• Keep components cohesive. A component should implement a single, related set of functionality. User-interface logic for one application, business classes for one domain concept, or technical infrastructure for one concern (security, persistence).
• UI classes go in application components. Screens, pages, reports, and the glue logic that wires them together belong in a UI-stereotyped component.
• Technical classes go in infrastructure components. Security, persistence, middleware, logging belong in <<infrastructure>> components shared across the system.
• Assign hierarchies to the same component. Inheritance and composition hierarchies almost always belong together; splitting them creates artificial component coupling.
• Minimise inter-component message flow. Two components that talk constantly are a sign they should be one component.
• Define component contracts as interfaces. Every service a component offers to its clients is an interface; this is what makes the component substitutable.

Deployment diagrams

A deployment diagram shows the runtime configuration of the system: which software runs on which hardware (or virtual) nodes, and how the nodes connect. It is the right diagram when the system is non-trivially distributed.

Notation:

• Nodes: 3D boxes representing a hardware or software execution environment. Common stereotypes: <<server>>, <<client>>, <<database>>, <<mobile device>>.
• Artifacts: deployable items on a node. Drawn as a rectangle with a <<artifact>> stereotype and a small document icon. Executables, configuration files, databases.
• Communication paths: lines between nodes, often labelled with the protocol (HTTPS, JDBC, AMQP).
• Component-to-node mapping: components from a component diagram are placed inside nodes to show which node hosts which component at runtime.

Architecture vs architectural style

A small but useful distinction:

• An architectural style is a pattern for a system layout. Examples: layered, client-server, peer-to-peer, three-tier, model-view-controller (MVC), pipes-and-filters, service-oriented (SOA).
• A software architecture is an instance of a style, applied to a specific system. The deployment diagram above is an instance of the 3-tier style.

From elicitation to first-cut model: one requirement, all the way through.

The earlier sections cover each diagram in isolation. This section walks one user requirement from the elicitation interview to a first-cut design, showing the substance at each step. The example is intentionally small so the full trace fits on this page; on a real project, every requirement goes through this same chain.

Stage 1: Elicitation snippet

In a structured interview with the head librarian of the Birzeit Main Library, the analyst captures the following extract (paraphrased to the level of detail an interview transcript would record):

Notice what the interview transcript already contains, even before any modelling: an actor (BookBorrower, called "the student"), a sub-actor implied (Librarian, the speaker), a business rule (max six items), a domain rule (loan periods depend on book type), a normal flow, an exception (damaged barcode), and an alternative outcome (loan refused). The analyst's job in the next stage is to write that down in a form that survives months of execution.

Stage 2: User Requirement (UR) and System Requirements (SR)

The transcript converts into one UR with two SR refinements. The numbering follows the convention used in Ch.3 section 3.

Each SR is a developer-precise refinement of UR3 (note the shared prefix). Each is testable: SR3.1 corresponds to a test case for the seventh-loan refusal, SR3.2 to a parameterised test of the three loan periods, SR3.3 to a manual-entry test plus exception verification.

Stage 3: Effort estimate for UR3

Using the per-UR method from Ch.3 section 11, the team estimates UR3 as follows. The estimate is in person-weeks (pw); the calculator in Ch.3 takes these numbers and rolls them up into the project total.

This estimate is what the customer is asked to authorise. If the customer later asks for "also support overdue notifications", a new UR is added, re-estimated, and added to the project total before any work begins.

Stage 4: Use case ellipse and description

UR3 maps to one primary use case (Borrow copy of a book) plus its refinement use cases (Compute return date as <<include>>, Refuse loan as <<extend>>). The diagram form is in figure 3 above; the textual form, expanded into the eight-field template used throughout section 8, looks like this:

This textual description is the contract; the ellipse on the diagram is the index entry. The activity diagram (section 9) would draw steps 1 through 7 as actions in swimlanes for BookBorrower, Librarian, and System, with a decision diamond at step 3 splitting the normal and refusal branches. The sequence diagram (section 11) would draw the messages between Librarian, System, BookCopy, Loan, and PersistenceStore for the normal scenario.

Stage 5: First-cut class fragment

From the noun-verb analysis of the UR / SR text (section 10): nouns LibraryMember, Book, BookCopy, Loan, Librarian; attributes loan count, status, barcode, start_date, return_date, type; verbs borrow, return, compute return date, refuse. The first-cut class diagram fragment for UR3 is:

Three observations worth taking away from the fragment:

• Every SR has a home. SR3.1 (max six loans) is the 0..6 multiplicity on the borrows association. SR3.2 (compute return date) is the computeReturn() operation on Loan. SR3.3 (manual barcode entry, damaged-barcode exception) does not appear here because it is a workflow concern; it lives in the activity diagram for the use case, not in the class fragment.
• Aggregation vs composition is a domain decision, not a notation choice. Book aggregates BookCopy because copies survive the deletion of the catalogue record (they are physical books on the shelf). If we were modelling an e-book platform where deleting a Book also deleted its copies, composition would be correct.
• The class fragment surfaces a question the requirements missed. The Loan association class implies a Loan has a single member at a time. But what about historical loans (a copy borrowed by two members at different times)? The class diagram makes the team ask whether Loan instances are kept after return, and at the point that question is asked, the team goes back to UR3 and adds: "the system shall keep loan history for at least seven years for audit." That is the iteration loop in figure 1 made concrete.

What this thread illustrates

One requirement, five artefacts, each refining the previous and each surfacing questions the previous stage missed. The work of UML modelling is not drawing pretty ellipses; it is the disciplined re-asking, at progressively finer detail, of "what exactly does the system do?". A model that lets you skip the re-asking is not a useful model. A model that forces the re-asking, and lets the team write the answers down so they survive the project, is the artefact this chapter is teaching you to produce.

Eight modelling pitfalls that show up in practice.

Drawn from Fowler's UML Distilled, recurring review findings on real UML models, and Brooks' general observations about modelling.

Sources cited above, and where to go next.

The course textbook and Prof Adel's lecture notes anchor the chapter; the books below are the works directly referenced in the text and the standard practitioner references.

Course material

UML, primary references

Originals that fed into UML

Class and component design

Adjacent course material