Step 10: Model and document

What you get from this step

You get a written architecture that its readers can use. It fills four sections of the arc42 template:

Section 3, Context and Scope: the system as a black box with its users and neighbor systems.
Section 5, Building Block View: the static parts of the system and how they relate.
Section 6, Runtime View: a few chosen scenarios that show how the parts work together.
Section 7, Deployment View: which hardware and environments run which parts.

You draw these sections with three notations. C4 fits context and containers. UML fits sequence and deployment diagrams. BPMN fits business processes. UML is a notation, not a method, so it works alongside whatever method your team already uses.

What you need first

A list of stakeholders (people with an interest in the system) and what each expects. See Introduction and Goals and Stakeholder Perspective and Concern.
The top three to five quality goals, each with a short scenario.
The constraints that limit your design, with a note on which can be negotiated. See Constraints.
A short list of the fundamental decisions. See Solution Strategy.

If something is missing

No stakeholder list: ask the likely readers what they want to learn from the documentation. Write down their answers. Characteristics of a Good View asks for this record.
No quality goals: agree on the three that matter most to the main stakeholders. Add them to section 1 before you draw. They tell you where detail is worth the effort.
No constraints or strategy: write a short keyword list for each. Add reasons. Refine it later.
No agreed notation: pick one now and write it down. See step 2 below.

How to do it

Choose views from reader questions. Each view answers questions from named stakeholders. Write the stakeholders and their concerns at the top of each view. Do not build one model that shows everything. See Stakeholder Questions Addressed in Views and Architectural View.
Agree on a short modeling method. Every diagram gets a title with its type and scope, plus a legend. Every arrow gets a specific label. Colors mean the same thing in every diagram. Name each element’s type. See Modeling Method and Rules of Thumb for Modeling. Avoid vague labels such as “uses”.
Write section 3. Draw the business context first. It shows the system as a black box, with the data that flows to and from each partner. Arrows show data flows, not dependencies. Then write the technical context separately. It maps each data flow to the channel or protocol that carries it. Add a table that describes each interface. A C4 system context diagram works well here. Keep technologies out of the business diagram. See Business and Technical Context, Context and Scope and Context View Antipatterns.
Write section 5. Level 1 is the white box (the inside view) of the whole system. It shows the top-level building blocks as black boxes (outside view only: responsibility and interfaces). A C4 container diagram is a good level 1. A container is an application or data store that must run for the system to work. Show each container’s main technology and label each arrow. Then refine only the blocks that are important, risky, complex or volatile. Leave simple parts alone. Group blocks by responsibility, not by code package names. See Component View, Component View Refinement Levels and Lifting Code to Model Level. Draw a C4 component diagram only where it adds value. Skip code-level diagrams unless a component is critical or complex. If you need one, generate it with a tool.
Write section 6. Pick a few scenarios for their architectural relevance. Good candidates are a key use case, an external interface, start-up or administration, and an error case. Do not try to cover every flow. Draw each as a sequence diagram so each building block’s responsibility is visible. Use building block names, not code names. For a process that spans several parties, a BPMN collaboration diagram fits. It gives each participant its own pool and connects pools with message flows. Check BPMN models for deadlocks. See Runtime View, Code-Level Activity Diagram antipattern and Soundness of Process Models.
Write section 7. Map the building blocks onto hardware and infrastructure with a UML deployment diagram. Draw one diagram per environment. Show infrastructure nodes such as load balancers and firewalls where they matter. Label each connection with its protocol. Say how the infrastructure influences the system. See Deployment View, Deployment View Antipatterns and Deployment Diagram Modeling Mistake.
Describe each thing once. Describe an interface in one place and reference it elsewhere. Keep the document short. Record reasons for important decisions. Name one person who is responsible for how much is written and how good it is. See Guidelines for Documentation and Undetected Duplication Antipattern.
Store diagrams so they stay current. Keep diagram sources as text in version control. Name the renderer. Rebuild the diagrams when you build the documentation. See Diagrams as Code and Documentation as Code.
Review each diagram. Check for a title, a legend, labeled arrows, one abstraction level, and element types. See Architectural Overview Antipattern and Unclear Level of Abstraction.

Example: ClinicBook

ClinicBook is an online booking system for 40 small medical practices. Its main forces are privacy and security, availability during morning peaks, integration with legacy practice software, a small team, and a fixed launch date. The team is small, so it writes less and aims at what is risky.

Readers. The team lists four groups: the developers, the operations person, the privacy officer, and the practice owners who pay for the system. Developers ask what the parts are. Operations asks where it runs. The privacy officer asks where health data goes. The practice owners ask which systems ClinicBook touches. Each answer points to a view.

Section 3. The business context shows ClinicBook as one black box. Its partners are patients, practice staff, the practice-management software of each practice, an SMS provider and an e-mail provider. The arrows carry data:

Partner	Data to ClinicBook	Data from ClinicBook
Patient	Booking, move and cancel requests	Confirmations, reminders
Practice staff	Calendar changes	Appointment lists
Practice-management software	Free slots, changed appointments	New, moved and canceled appointments
SMS and e-mail providers	Delivery status	Reminder messages

The technical context is a separate diagram and table. Patients and staff reach ClinicBook over the web and a mobile app. Each practice-management vendor gets its own row, because each channel differs. The team does not put these channels into the business diagram.

Section 5. Level 1 is a container diagram. It shows a web app, a mobile app, a booking back end, a database, a notification part, and an integration part for the practice-management software. The database appears as a container because the system needs it to run. The team refines only two blocks. The integration part is refined because the vendors differ and it is the riskiest. The booking back end is refined because the privacy and morning-peak goals meet there. The web and mobile apps stay black boxes. The team writes no code-level diagrams.

Section 6. The team picks three scenarios:

A patient books an appointment. This is the key use case, drawn as a sequence diagram.
A patient books while a practice’s software is unreachable. This is an error case.
Reminders go out by SMS and e-mail. This is an external interface.

For moving an appointment, which involves the patient, ClinicBook and the practice software, the team draws a BPMN collaboration diagram with one pool per participant. Each step names the building block that does the work.

Section 7. The team draws one deployment diagram for production. It shows the firewall, a load balancer, several application nodes, and a database node. The text explains why: morning peaks need more than one application node. A staging environment gets its own diagram only if it differs.

Care. Every diagram has a title, a legend and labeled arrows. The team stores sources as text in Git. One team member owns the documentation.

Done when

Every diagram has a title with type and scope, a legend, and labeled arrows. See Modeling Method.
Section 3 shows the system as a black box with data flows, and the technical context is kept separate. See Business and Technical Context.
Section 5 has a level 1 white box with black boxes, and deeper levels refine only selected blocks. See Component View Refinement Levels.
Section 6 holds a small set of relevant scenarios, and each activity maps to a building block. See Runtime View.
Section 7 maps building blocks to hardware, one diagram per environment. See Deployment View.
Each view names its stakeholders and their concerns. See Architecture View.
Every interface is described once, and a named person owns the documentation. See Guidelines for Documentation.