Skip to content
Software Architecture Guide

Step 2: Define scope and context

What you get from this step

Section titled “What you get from this step”

You get a clear line between your system and everything around it. You also get a context view: one picture and two tables that show who and what the system talks to. This is arc42 section 3, described in arc42 Context and Scope.

The result has three parts:

  • A business context: which data the system exchanges with people and neighboring systems. See Business and Technical Context.
  • A technical context: which channels and protocols carry that data.
  • A context table with one row per communication partner.

A communication partner is any user or IT system that exchanges data with your system. The system itself is drawn as a black box: you see its borders and its neighbors, but nothing inside. See Context View.

What you need first

Section titled “What you need first”
  • A short statement of what the system must achieve and its top quality goals (at most five). See arc42 Introduction and Goals.
  • A list of stakeholders, meaning people, teams and organizations with an interest in the system. See Stakeholder Identification.
  • The known constraints, meaning requirements that limit your design choices. See arc42 Constraints.
  • A first list of users and neighboring systems, even if it is incomplete.

If something is missing

Section titled “If something is missing”
  • No stakeholder list. Make a quick one. Ask who gains or loses, who decides, and who controls resources. See Stakeholder Identification.
  • No quality goals yet. Write down the three to five that matter most. Keep them short. See arc42 Introduction and Goals.
  • You do not know a partner or its interface. Draw the partner anyway. Mark the gap as a risk in the context. See Context View.
  • You are unsure whether something is in scope. Write down the boundary decision and state it openly. Do not leave it implicit. See Architecture Disciplines.
  • The system uses outside data. Treat the data source as an external system. See Use of external and open data.

How to do it

Section titled “How to do it”
  1. State the boundary. Write one sentence on what is inside the system. Decide for each unclear part whether it is inside or outside, and record the decision. See Architecture Disciplines.
  2. List all communication partners. Include human users and IT systems. Include external data sources too. For open data, note the license (or that it is public domain), that it is machine-readable, and how you obtain it. See Use of external and open data.
  3. Draw the system as one box. Put it in the middle. Put the partners outside the boundary. Show people and systems, not technologies. See System Context Diagram.
  4. Draw the business context. Each arrow shows data that flows, not a dependency. Label every arrow with the data. If data moves both ways, show both directions. See Business and Technical Context and Context View Antipattern: Forgetting Bidirectional Data Flows.
  5. Keep it an overview. Show no system internals. If there are many external systems, group them by stated criteria. Describe each interface in detail elsewhere. See Refining Complex Context Views.
  6. Write the technical context separately. For each domain interface, name the channel or protocol that carries it. Keep this apart from the business context. See arc42 Context and Scope.
  7. Add a context table. Give each partner one row: a short name, why it matters to the business, and the data exchanged. Describe each interface in one place only, and point to it from elsewhere. See Undetected Duplication Antipattern.
  8. Make the diagram readable. Give it a title that states its type and scope. Add a legend for shapes and line styles. Use plain names, and spell out acronyms. See Architectural Overview Antipattern.
  9. Mark risks. Flag partners or interfaces you do not understand yet. See Context View.

Example: ClinicBook

Section titled “Example: ClinicBook”

ClinicBook is an online booking system for 40 small medical practices.

Boundary decisions. The web app, the mobile app and the calendar functions are inside ClinicBook. The practices’ existing practice-management software is outside. So are the SMS and e-mail delivery services. ClinicBook does not own them.

Partners.

  • Patients, who use the web or the mobile app.
  • Practice staff.
  • Practice-management software, from different vendors.
  • An SMS service.
  • An e-mail service.

No open data source is planned. If one is added later, it would appear as an external system, with its license stated.

Diagram: Business context of ClinicBook (system context, whole system)

 Patient  <--(1)-->  +------------+  <--(3)-->  Practice-management software
                     | ClinicBook |
 Practice <--(2)-->  |  (system   |  --(4)-->   SMS service
 staff               | black box) |  --(5)-->   E-mail service
                     +------------+

Legend: A box is the system or a partner. Arrows show data flow in the arrow’s direction. Double-headed arrows carry data both ways. Numbers refer to the table below.

Business context table.

# Partner Data into ClinicBook Data out of ClinicBook
1 Patient Booking, move and cancel requests Free slots, confirmations
2 Practice staff Calendar changes Calendar and appointment lists
3 Practice-management software Existing appointments and calendar data New, moved and canceled appointments
4 SMS service none Reminder text for a patient
5 E-mail service none Reminder e-mail for a patient

Technical context table (separate).

# Channel
1 Web browser and mobile app, over the internet
2 Web browser, over the internet
3 Differs by vendor. Not yet clarified for some vendors.
4, 5 Provider interfaces, to be chosen

Risks marked in the context.

  • Reminders and appointment data can reveal health information, so rows 1 to 5 need privacy review.
  • Row 3 is a risk, because the vendors’ interfaces differ and some are unknown. The team treats it as the main integration risk.

Done when

Section titled “Done when”

Learn more

Section titled “Learn more”