# 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](https://arc.fuet.ch/concepts/documentation/arc42-documentation-template.md):

- **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](https://arc.fuet.ch/concepts/documentation/c4-model.md) fits context and containers. [UML](https://arc.fuet.ch/concepts/modeling-uml/uml-unified-modeling-language.md) fits sequence and deployment diagrams. [BPMN](https://arc.fuet.ch/concepts/modeling-bpmn/bpmn-motivation.md) 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](https://arc.fuet.ch/concepts/documentation/arc42-introduction-and-goals.md) and [Stakeholder Perspective and Concern](https://arc.fuet.ch/concepts/documentation/stakeholder-perspective-and-concern.md).
- 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](https://arc.fuet.ch/concepts/documentation/arc42-constraints.md).
- A short list of the fundamental decisions. See [Solution Strategy](https://arc.fuet.ch/concepts/documentation/arc42-solution-strategy.md).

## 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](https://arc.fuet.ch/concepts/documentation/characteristics-of-a-good-view.md) 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

1. **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](https://arc.fuet.ch/concepts/documentation/stakeholder-questions-addressed-in-views.md) and [Architectural View](https://arc.fuet.ch/concepts/documentation/purpose-of-views.md).
2. **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](https://arc.fuet.ch/concepts/documentation/modeling-method.md) and [Rules of Thumb for Modeling](https://arc.fuet.ch/concepts/documentation/rules-of-thumb-for-modeling.md). Avoid vague labels such as "uses".
3. **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](https://arc.fuet.ch/concepts/documentation/c4-level-1-system-context-diagram.md) works well here. Keep technologies out of the business diagram. See [Business and Technical Context](https://arc.fuet.ch/concepts/documentation/business-and-technical-context.md), [Context and Scope](https://arc.fuet.ch/concepts/documentation/arc42-context-and-scope.md) and [Context View Antipatterns](https://arc.fuet.ch/concepts/documentation/context-view-antipatterns.md).
4. **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](https://arc.fuet.ch/concepts/documentation/c4-container-diagram.md) 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](https://arc.fuet.ch/concepts/documentation/component-view.md), [Component View Refinement Levels](https://arc.fuet.ch/concepts/documentation/component-view-refinement-levels.md) and [Lifting Code to Model Level](https://arc.fuet.ch/concepts/documentation/component-view-antipattern-lifting-code-to-model-level.md). Draw a [C4 component diagram](https://arc.fuet.ch/concepts/documentation/c4-level-3-component-diagram.md) only where it adds value. Skip [code-level diagrams](https://arc.fuet.ch/concepts/documentation/c4-level-4-code-diagram.md) unless a component is critical or complex. If you need one, generate it with a tool.
5. **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](https://arc.fuet.ch/concepts/modeling-uml/sequence-diagram.md) 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](https://arc.fuet.ch/concepts/modeling-bpmn/bpmn-collaboration-diagram.md) fits. It gives each participant its own pool and connects pools with message flows. Check BPMN models for deadlocks. See [Runtime View](https://arc.fuet.ch/concepts/documentation/runtime-view.md), [Code-Level Activity Diagram antipattern](https://arc.fuet.ch/concepts/documentation/runtime-view-antipattern-code-level-activity-diagram.md) and [Soundness of Process Models](https://arc.fuet.ch/concepts/modeling-bpmn/soundness-of-process-models.md).
6. **Write section 7.** Map the building blocks onto hardware and infrastructure with a UML [deployment diagram](https://arc.fuet.ch/concepts/modeling-uml/deployment-diagram.md). 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](https://arc.fuet.ch/concepts/documentation/distribution-view.md), [Deployment View Antipatterns](https://arc.fuet.ch/concepts/documentation/distribution-view-antipatterns.md) and [Deployment Diagram Modeling Mistake](https://arc.fuet.ch/concepts/modeling-uml/deployment-diagram-modeling-mistakes.md).
7. **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](https://arc.fuet.ch/concepts/documentation/guidelines-for-documentation.md) and [Undetected Duplication Antipattern](https://arc.fuet.ch/concepts/documentation/undetected-duplication-antipattern.md).
8. **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](https://arc.fuet.ch/concepts/documentation/diagrams-as-code.md) and [Documentation as Code](https://arc.fuet.ch/concepts/documentation/documentation-as-code.md).
9. **Review each diagram.** Check for a title, a legend, labeled arrows, one abstraction level, and element types. See [Architectural Overview Antipattern](https://arc.fuet.ch/concepts/documentation/architectural-overview-antipatterns.md) and [Unclear Level of Abstraction](https://arc.fuet.ch/concepts/documentation/unclear-level-of-abstraction-antipattern.md).

## 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](https://arc.fuet.ch/concepts/documentation/modeling-method.md).
- Section 3 shows the system as a black box with data flows, and the technical context is kept separate. See [Business and Technical Context](https://arc.fuet.ch/concepts/documentation/business-and-technical-context.md).
- Section 5 has a level 1 white box with black boxes, and deeper levels refine only selected blocks. See [Component View Refinement Levels](https://arc.fuet.ch/concepts/documentation/component-view-refinement-levels.md).
- Section 6 holds a small set of relevant scenarios, and each activity maps to a building block. See [Runtime View](https://arc.fuet.ch/concepts/documentation/runtime-view.md).
- Section 7 maps building blocks to hardware, one diagram per environment. See [Deployment View](https://arc.fuet.ch/concepts/documentation/distribution-view.md).
- Each view names its stakeholders and their concerns. See [Architecture View](https://arc.fuet.ch/concepts/documentation/architecture-view.md).
- Every interface is described once, and a named person owns the documentation. See [Guidelines for Documentation](https://arc.fuet.ch/concepts/documentation/guidelines-for-documentation.md).

## Learn more

- [arc42 Architecture Documentation Template](https://arc.fuet.ch/concepts/documentation/arc42-documentation-template.md)
- [C4 Model](https://arc.fuet.ch/concepts/documentation/c4-model.md)
- [Unified Modeling Language (UML)](https://arc.fuet.ch/concepts/modeling-uml/uml-unified-modeling-language.md)
- [Why Use UML in Architecture Documentation](https://arc.fuet.ch/concepts/modeling-uml/why-use-uml-in-architecture-documentation.md)
- [BPMN Collaboration Diagram](https://arc.fuet.ch/concepts/modeling-bpmn/bpmn-collaboration-diagram.md)
- [BPMN Modeling Guidelines](https://arc.fuet.ch/concepts/modeling-bpmn/bpmn-modeling-tips.md)
- [Matching Diagram Type to System Aspect](https://arc.fuet.ch/concepts/modeling-uml/matching-diagram-type-to-system-aspect.md)
- [Model vs. View](https://arc.fuet.ch/concepts/documentation/model-vs-view.md)
- [Essential Architecture Views](https://arc.fuet.ch/concepts/documentation/contemporary-essential-views.md)
- [Architecture Viewpoint](https://arc.fuet.ch/concepts/documentation/architecture-viewpoint.md)
- [Additional Architecture Viewpoints](https://arc.fuet.ch/concepts/documentation/additional-architecture-views-and-perspectives.md)
- [Kroki](https://arc.fuet.ch/concepts/documentation/kroki.md)
- [Modeling Tool vs. Drawing Tool](https://arc.fuet.ch/concepts/modeling-uml/modeling-tool-vs-drawing-tool.md)
- [Self-Invented Notation Drawback](https://arc.fuet.ch/concepts/documentation/self-invented-notation-drawback.md)