Before you start: what should already exist

Vision and system idea

What it is The vision is a short statement of the shared goal behind the product. A good Vision Statement names the target customers, the value they get, and the few features that make the product stand out. The system idea is an early, rough answer to how the system will work. See System Idea and System Idea and Vision Elements.

Why you need it Architecture serves a purpose. The vision states that purpose in a few lines, and it ties the value of the product to business goals. Without it, people on the team may each picture a different product. The system idea gives the first design decisions something to start from. The later solution strategy refines it, driven by quality goals and constraints.

Who usually provides it The business side owns the “why”, because the vision links value to business goals and the business case. The system idea is a first technical sketch, so the people who will design the system add to it.

Good enough is A few sentences, not a document. You can read it aloud in under a minute. It names who the product is for, what value they get, and one or two standout features. The system idea can be a rough sketch that you expect to change.

For ClinicBook, a good-enough version could read: “ClinicBook lets patients of our 40 practices book, move and cancel appointments on the web or in an app. Practice staff keep their own software, and ClinicBook keeps their calendars in sync. Reminders go out by SMS and e-mail.” A matching system idea could be one line: a web and mobile front end, plus one connection to each practice’s software.

If it is missing Write a first draft yourself from what you already know, and show it to the people who own the product. Do not wait for a perfect version. Requirements and architecture grow together from a rough start, as the Twin Peaks Model describes. Early decisions may prove wrong, and you can correct them later (see Architecture Challenges at Project Start).

Business goals

What it is Business goals are the results the organization wants from the system. Business requirements belong in a vision and scope document, kept apart from detailed software requirements (see Requirement Types and Documents (Wiegers/Beatty)). The Business Model Canvas is one way to see the business behind a system on a single page.

Why you need it Business goals show which parts of the system carry the most value. They also help you judge which quality demands are worth their cost. An important requirement that you cannot link to business value or risk is a warning sign (see Architecturally Significant Requirement).

Who usually provides it The business side states these goals, for example in a vision and scope document. If the organization has a canvas, read it. A cited canvas should carry a date and a version.

Good enough is Three to five goals, each worded so you can tell later whether it was met. Ideally you can name how you would check each one, as the SMART Requirements checklist asks.

For ClinicBook, assume these example goals: practices spend less staff time on phone bookings; patients can reach a booking at any hour; ClinicBook launches on the fixed date. The numbers behind them come from the business side, not from the architects.

If it is missing Ask for it directly. Then write down your best guess and mark it as an assumption. Check it with the people who own the product. Treat gaps as normal: requirements are never complete and will change (see Requirements Trawling).

Stakeholders and their concerns

What it is A Stakeholder is a person, team, organization or class of such parties with an interest in the system. A concern is something a stakeholder cares about, such as security or speed (see Stakeholder Concern and Concern). Stakeholder Identification is the step of finding them.

Why you need it Concerns shape what the architecture must address. Concerns can also conflict, for example time-to-market against maintainability. You can only weigh a conflict if you know who holds each side. A written overview prevents surprises later in development.

Who usually provides it The team that designs the system builds the list. The stakeholders themselves supply their expectations. Every stakeholder class needs a representative, so no class is ignored.

Good enough is A table with role or name, contact and expectations, linked to concerns. Guiding questions help you fill it: who gains or loses, who decides, who controls resources. Consider every class, such as acquirers and assessors. To plan how closely to engage each group, you can sort them with the Stakeholder Power Grid.

For ClinicBook, the table could include:

Stakeholder	Concern
Patients	Book quickly, trust that health data stays private
Practice staff	Calendars that are correct and current
Practice owners	Cost, and a working launch on the fixed date
Vendors of practice-management software	A clear, stable interface
Development team	A design a small team can build and change

If it is missing Start the table with the guiding questions above, even with only a few rows. Note which stakeholder classes still lack a representative. Keep the table open, since new stakeholders often appear later.

Scope and context

What it is Scope says what the system covers. Context shows the system as a black box, meaning you see only its outside, with the world around it. The Context View focuses on the data the system exchanges with its environment, so everyone can see where the system starts and ends. This is arc42 section 3.

Why you need it Every interface to the outside is a source of design work and risk. If you miss a neighbor, you miss an interface. The context view also marks risks explicitly.

Who usually provides it The architecture team draws it. The stakeholders confirm that all communication partners appear, because everyone should be able to understand it.

Good enough is One overview diagram plus a table with one row per communication partner, as Refining Complex Context Views suggests. Label each flow with the data exchanged. Show both directions where data flows both ways (see Context View Antipattern: Forgetting Bidirectional Data Flows). If there are many neighbors, group them by stated criteria.

For ClinicBook, the neighbors are patients (web and app), practice staff, the practice-management software, the SMS service and the e-mail service. The practice software exchanges data in both directions. ClinicBook sends bookings and receives calendar changes. With different vendors, grouping them by vendor keeps the picture readable. Mark the unknown vendor interfaces as risks.

If it is missing List every person and system that talks to the system. Draw the black box, and add a table row for each partner. Where you do not know the data or channel yet, say so and mark it as a risk.

Key functional requirements

What it is Functional requirements say what the system must do. Keep them apart from quality requirements and constraints (see Working with Functional Requirements (method phase)). Teams often write them as use cases or user stories. A Use Case describes how the system responds to outside actors. A User Story is a short reminder to talk, with details added through conversation.

Why you need it Functions alone do not fix the design. Still, architects need the key ones to see the main flows and responsibilities. Detailed requirements are only needed for the subset that drives architectural decisions.

Who usually provides it Requirements documents usually exist already. Your overview should refer to them instead of copying them. Customer representatives supply the details.

Good enough is A brief list of the key functions, each one a goal a user can reach in one sitting (see Use Case Goal Level). Large items are split into parts that still deliver value. A word like “manage” is a signal to split by operation (see Story Splitting).

For ClinicBook, the list could read: patient books an appointment; patient moves it; patient cancels it; staff view the practice calendar; staff block time off; the system sends a reminder. “Manage calendars” is too vague, so it becomes “view” and “block time off”.

If it is missing Write the short list yourself, then confirm it with the customer representatives. Do not wait for a full specification. Requirements trawling accepts that some requirements are overlooked and some appear only during building.

Top quality goals

What it is Quality goals say how well the system must do its job, such as how secure or fast it is. Teams cannot maximize all of them at once, so they rank them (see Quality Attribute Prioritization). Arc42 section 1 lists the top three, at most five. Section 10 holds the rest. ISO/IEC 25010 Product Quality Model offers a shared vocabulary.

Why you need it Quality goals shape a system as much as features do. A change to one goal can force a different solution (see Insufficient Quality as Driver of Change). Improving one quality usually costs another (see Quality Attribute Trade-off).

Who usually provides it The most important stakeholders rank them. A Utility Tree is one way to build the list, and decisive stakeholders should take part in building it.

Good enough is A table, ordered by priority, with at most five rows. Each row has at least one concrete scenario with a measurable response (see Quality Attribute Scenario). Avoid buzzwords.

For ClinicBook, the table could read:

1. Security and privacy of health data. See Security Scenario.
2. Availability in the morning peak. See Availability Scenario. An example scenario: “On a weekday between 08:00 and 09:00, one server fails while patients are booking. Booking continues, and the patient sees no error.” The time window and any numbers are placeholders that stakeholders must agree on.
3. Interoperability with the practices’ existing software. See Interoperability Scenario.

If it is missing Run a short workshop with key stakeholders. Start from a standard list such as ISO/IEC 25010, then pick the top three and write one scenario for each. No list is complete, so also ask which qualities are missing from it. Keep the others for section 10.

Constraints

What it is A constraint is a requirement that limits how freely you can design and build (see Architectural Constraint). Technical constraints, such as required platforms or interfaces, are the focus here. Constraints can also be organizational or political, or come from conventions. Arc42 section 2 lists them. Constraints differ from forces, which you weigh against each other (see Architectural Force).

Why you need it Writing constraints down in one place shows where the design is free and where it is not. Some constraints can be negotiated, so note which ones. Also note which ones apply across the whole organization.

Who usually provides it Each constraint should name who wants it and why. That points you to the person who can explain it, or negotiate it.

Good enough is One list, grouped by kind. For each constraint, give the source, the reason and the consequence, such as extra cost or effort.

For ClinicBook, a technical entry could read: “ClinicBook must work with the practices’ existing software, from several vendors. Source: the practices. Reason: they will not replace it. Consequence: integration effort for each vendor.” Add that rules for health data may bind the design, and ask who owns that rule. The fixed launch date belongs in the organizational group. Note whether anyone can move it.

If it is missing Ask each stakeholder what they require, and record each answer with its source. For each one, ask whether it can be negotiated. Until you know, assume it binds you.