Skip to content
Unit 8 of 18
RFPLumen DiagnosticsOpen anytime - every module Task uses this brief

Module 5 — Architecture Modeling

Contents · 17

What you'll be able to do

  • Choose a notation — informal, UML, BPMN, ArchiMate or C4 — that fits the audience and the question the diagram must answer
  • Draw C4 system context and container diagrams that meet C4's notation rules: a key, typed elements, and every relationship labelled with intent, technology and direction
  • Pick the right behaviour diagram for a question, and draw a sequence diagram that exposes the ordering, waiting and failure handling a structure diagram hides
  • Tell a model from a diagram, and decide when diagrams as code, a Structurizr model or an ArchiMate repository earns its cost
  • Review a diagram against named hygiene rules and fix what fails

Opening questions worth asking yourself: how often do you create diagrams and do modelling? What kinds of diagrams do you create? What tools do you use?


Notation formality

Notations fall into three categories by formality. Usage runs the other way: the less formal the notation, the more widely it is used.

CategoryExamplesCharacter
InformalBoxes and linesWidest usage
Semi-formalUML, BPMN, ArchiMateMiddle
FormalAADL (SAE Architecture Analysis & Design Language), used for safety-critical embedded systems such as a vehicle speed-control systemNarrowest

A diagram without a key makes it genuinely difficult to identify the different elements. Try it: show a colleague any boxes-and-lines diagram with its legend removed and ask what the dashed arrows and the grey boxes mean. Always provide a legend.


UML

UML's diagram set splits into two top-level categories: structural diagrams (class, object, package, profile, composite structure, component, deployment) capture the static shape of a system, while behavioural diagrams (use case, activity, state machine, sequence, communication, timing, interaction overview) capture how it behaves over time. This structural/behavioural split is the organising principle behind UML 2.5's fourteen diagram types — seven of each, with sequence, communication, timing and interaction overview grouped as interaction diagrams inside the behavioural half. Class, sequence and use case are simply the most frequently used in practice.

Rendering diagram…

The UML specification is updated and managed by the Object Management Group. The first versions were created by the "Three Amigos" — Grady Booch (creator of the Booch method), Ivar Jacobson (Object-Oriented Software Engineering, OOSE), and Jim Rumbaugh (Object-Modeling Technique, OMT).

VersionDateChange
1.303-2000A number of changes to the UML metamodel, semantics and notation, but considered a minor upgrade to the original proposal
1.4.201-2005Accepted as ISO specification ISO/IEC 19501. (UML 1.5 was released two years earlier)
2.007-2005New diagram types: composite structure, interaction overview, timing; package and object diagrams, used informally in 1.x, became named diagram types. Collaboration diagrams renamed communication diagrams
2.202-2009Profile diagram added
2.506-2015Called a "minor revision" to UML 2.4.1, but the specification document was substantially simplified and reorganised to make it easier to read — for example by reducing forward references
2.5.112-2017Current version; a minor revision of 2.5

Full UML is used less than it once was. The three diagrams that survive best in practice: class, sequence, use case.

Where your audience does not read UML, "boxes and lines" are acceptable for any view — provided the diagram carries a key, as above.


BPMN, ArchiMate and behavioural diagrams

BPMN (OMG; current version 2.0.2, also published as ISO/IEC 19510) is semi-formal. Beyond the standard process diagram:

  • Conversation diagrams — a high-level view of which participants exchange related messages, grouping those exchanges into conversations without showing each message
  • Choreography diagrams — the ordered sequence of message exchanges between participants, with no single participant's process in control

BPMN also defines its own symbol vocabulary worth knowing by name: gateways (exclusive, inclusive, parallel, and event-based) control branching and merging of flow, pools and lanes partition a process by participant, and dedicated icon families distinguish task types (user, service, manual, script, send, receive, business rule) from event types (start, intermediate, end, each combinable with triggers like message, timer, signal, or error). BPMN 2.0 also distinguishes a process diagram, which models a single participant's internal flow, from a collaboration diagram, which shows multiple participants' pools exchanging message flows with each other.

ArchiMate (The Open Group) is a semi-formal enterprise architecture modelling language and the natural notation for the business-architecture views of Module 2. ArchiMate 3.2, still the version most tools support, organises elements into layers — strategy, business, application, technology, physical, and implementation and migration. ArchiMate 4 (April 2026) replaces the layers with domains and cuts the number of concepts from about 60 to 42. Its strength is the relationships across those layers — a business process served by an application service, which runs on a technology node — and that is what makes it the usual language of model repositories, covered below.

Two simpler notations outside the UML/BPMN/ArchiMate trio are also worth having: the flowchart/swimlane (also called a cross-functional diagram), which divides a process's steps into lanes by department, role, or system to show who is responsible for each step, and the mind map, which organises ideas as branches radiating outward from a single central concept rather than as a sequential flow.

Several notations describe behaviour, and they answer different questions. Choose by the question:

QuestionDiagramLumen example
In what order do a few participants interact in one scenario, and who waits for whom?UML sequence, or a C4 dynamic diagramOffer → patient accepts → booking confirmed, drawn later in this module
How does work flow through a process, with decisions and hand-offs between roles?UML activity, BPMN with pools and lanes, or a swimlaneToday's manual booking by the referral desk, by phone and email
What states can one thing be in, and what moves it between them?UML state machineAn appointment's stages, Requested → … → Billed
Where does data come from, where is it transformed, and where is it stored?Data flow diagramThe 15-minute referral extract on its way into the platform

The C4 model

The C4 model, proposed by Simon Brown (c4model.com), draws the static structure of a software system as a set of maps at increasing zoom, each traceable to the next and finally to code. Its premise is that a team cannot draw consistent maps until it agrees what the boxes mean, so C4 fixes a small set of abstractions — a shared vocabulary for structure — and every diagram uses them. Agree the local detail before anyone draws: which kinds of container your project has (web application, API, worker, database, queue) and what you will call a component.

Abstractions and the four levels

AbstractionMeaning
PersonA human user of the system, named by role
Software systemThe highest-level unit of value: your system, and each system it uses or serves. Usually owned by one team
ContainerSomething that must be running for the system to work: a web application, an API, a background worker, a database, a queue, a file store. Not a Docker container, though it may be deployed as one
ComponentA group of related functionality behind a well-defined interface, inside one container. Not separately deployable
CodeThe classes, functions or tables that implement a component
Rendering diagram…
LevelShowsMain readers
1. System contextThe system as a single box, the people who use it, and the systems it depends on or servesEveryone, including non-technical sponsors
2. ContainerInside that box: the containers, their responsibilities and technologies, and how they communicateArchitects, developers, operations
3. ComponentInside one container: its components and their interactionsThe architects and developers of that container
4. CodeInside one component: classes or tablesDevelopers. Usually generated by an IDE when needed, rarely drawn

Each level zooms into one box of the level above. Brown's own advice is that most teams need only the first two; draw component diagrams only for the containers complex enough to need them.

Notation rules

C4 prescribes no shapes or colours — it is notation-independent — but its notation guidance (c4model.com) sets rules every C4 diagram should meet. In summary:

  • A title naming the diagram type and scope: "Container diagram — Financial Risk System"
  • A key explaining every shape, colour, border style, line style and arrowhead used, and any acronym
  • Element types made explicit. Every box says whether it is a person, software system, container or component, and carries a one-line description of its responsibility
  • Technology on containers and components: "API application [Java, Spring Boot]", "Database [PostgreSQL]"
  • Relationships one-directional and labelled with intent. The arrow points the way the label reads — "Gets trade data from" points at the Trade Data System. Avoid two-headed arrows and single-word labels such as "Uses"
  • Technology or protocol on relationships between containers, since these are usually inter-process calls: "HTTPS/JSON", "SQL over TLS", "AMQP", "SFTP file every 15 minutes"

Add one convention of your own: say in the key whether arrows show dependency (who calls whom) or data flow (which way data moves). C4 allows either, and a reader cannot tell from the arrow alone.

Supplementary diagrams

The four levels show static structure. C4 adds three supplementary diagrams for what they cannot show:

DiagramShowsUse it when
System landscapeAll the software systems and people in an organisation or domain, with no single system in focusReaders need the estate before the solution — for Lumen, the referral system, identity service, SSO and finance systems alongside the new platform
DynamicHow elements from a static diagram collaborate at runtime for one feature or scenario, with the interactions numbered in orderOrder, timing or failure handling matters. C4 accepts a UML sequence diagram here; one is worked below
DeploymentHow container instances map onto infrastructure — regions, clusters, virtual machines, managed services — in one environment, such as productionYou need to show redundancy, regions, network boundaries or where TLS terminates. The physical view in Module 6 is one

C4 under critique: the Financial Risk System kata

Here C4 is examined critically, using Simon Brown's own Financial Risk System architecture kata as the example. The kata, in brief:

A global investment bank with offices in London, New York and Singapore trades financial products with other banks, its counterparties. Share-price movements make or lose it money, so at the end of each working day it must calculate its exposure to risk from the data it holds about its trades. Trade and counterparty data already live in two systems, the Trade Data System (TDS) and the Reference Data System (RDS); the bank needs a new Risk System.

Rendering diagram…

A simplified redraw of the kata's System Context diagram, kept deliberately close to the original so the critique below applies: no legend, every external system drawn as the same generic box, and relationship labels that rarely name a protocol.

Do you see any issues with the Context diagram? Check it against the notation rules above:

  • No key or legend
  • No element types. Every external element is the same generic "software system" box, though each could be named as what it is — Microsoft Exchange for e-mail, for example
  • Arrows rarely say how: what kind of communication, and what API does each external system offer? Only e-mail and SNMP are named
Rendering diagram…

One plausible container diagram for the kata, drawn with the same faults.

Do you see any issues with the Container diagram? Container level is where C4 adds technology choices and runtime structure, for developers and operations. This redraw has no key and no technology on any container or relationship, so the notation faults repeat. Fix those, and three objections to the model itself remain:

  • Too early for technology choice? C4 expects a technology on every container, and in a proposal or early design you may not have chosen one
  • No mapping of functional and non-functional requirements to containers. Nothing on the diagram says which container meets which requirement
  • Hard to use for a complex solution. With dozens of containers one diagram becomes unreadable; you have to split it by subsystem and lean on dynamic diagrams
Rendering diagram…

The Component diagram for the batch process repeats the notation faults: no key, no technologies, and labels that end in a vague "using".

In fairness to C4, most of these gaps belong to these particular diagrams rather than to the model: its notation rules ask for a key on every diagram, an element type on every box, and a technology or protocol on every relationship between containers. The criticisms that stick to the model itself are that it offers no way to trace requirements to containers, and that it expects technology choices at container level, which may be earlier than you want to commit. Both have cheap workarounds: carry requirement IDs in element descriptions or in a separate trace table (Module 6 builds one), and mark an undecided technology as a candidate — "[technology to be decided in discovery]" — rather than leaving it blank.

The context diagram, redrawn to the rules

The same kata context, fixed: a title, a key, typed elements with descriptions, and intent plus protocol on every relationship. The protocols and the e-mail product are illustrative assumptions; the kata does not fix them.

Rendering diagram…

Compare the two context diagrams side by side. Nothing about the system changed; what changed is that a reader who has never seen it can now say what each box is, what flows along each line, and over what.


Behaviour in practice: a Lumen booking flow

Structure diagrams show what exists and what talks to what. They cannot show order, waiting, or what happens when a step fails. For that, draw the critical flows. This one is the flow behind Lumen's ~$2 automated-booking target: an offer accepted by the patient and booked with the one partner group that has a scheduling API (about 15% of partner bookings, per the case). The participants are deliberately coarse — this is not a container diagram, and it is not yours.

Rendering diagram…

What it shows that a container diagram cannot:

  • Who waits for whom. The patient waits from step 3 to step 10 while the platform calls the partner. The partner's latency therefore falls inside the 2-second p95 target for routine screens (Module 3, QA02) — or the design must stop waiting. A container diagram shows only that the two are connected.
  • Synchronous versus asynchronous. Filled arrowheads are request and response; open arrowheads are fire-and-forget. Notifications are asynchronous, so a slow SMS gateway never delays a confirmation.
  • The failure branches. Between offer and acceptance the partner may give the slot away, or may not answer in time. The alt block forces decisions a box diagram never asks for — what the patient sees, which stage the referral returns to, who is told — and keeps the two cases apart: a slot that has gone means a new offer, while a timeout means a retry, because the booking may already exist.
  • Where state changes. The referral becomes Accepted when the patient accepts, but Confirmed only when the partner returns a booking reference — the moment the platform can claim to be the single source of truth for that appointment.
  • Retries need idempotency. If the booking call times out, the platform cannot tell whether the partner booked the slot. Retrying safely needs an idempotency key, which becomes a requirement on the partner interface you document in Module 6.

Two cautions. A sequence diagram shows one scenario, not the system: draw it for the few flows where order, timing or failure matter, not for every use case. And drawing one often exposes an alternative — here, replying "we are confirming your booking" at once and confirming asynchronously, so the patient never waits on the partner. Sketch the alternative too, then record the choice as a decision.


Diagrams as code, and modelling versus diagramming

A diagram is a picture; a model is the set of elements and relationships that pictures are drawn from. In a drawing tool, "Notification service" on three diagrams is three unrelated shapes: rename it on one and the other two are wrong, and nothing tells you. In a model it is one element that appears in three views; rename it once and every view changes. This is the cross-view consistency problem that Module 6 lists among the pitfalls of multiple views, solved by tooling rather than by care.

Two separate choices hide here: whether the source is text or a drawing, and whether there is one model behind many views, or one diagram per file.

Structurizr DSL (Brown's tooling for C4) is text and a model. You declare people, systems, containers and relationships once, then declare views that each include a subset. Relationships between containers are implied upward, so the context view shows "Business User → Financial Risk System" without your drawing it twice. A minimal workspace for the kata, with illustrative technologies:

workspace "Financial Risk System" {
    model {
        businessUser = person "Business User" "Reads the daily risk reports"
        frs = softwareSystem "Financial Risk System" "Calculates end-of-day risk" {
            webApp = container "Web Application" "Shows risk reports" "Java, Spring MVC"
            batch = container "Batch Process" "Imports data and calculates risk" "Java"
        }
        tds = softwareSystem "Trade Data System" "System of record for trades"

        businessUser -> webApp "Views risk reports using" "HTTPS"
        batch -> tds "Gets trade data from" "Nightly file export"
    }
    views {
        systemContext frs "Context" {
            include *
            autolayout lr
        }
        container frs "Containers" {
            include *
            autolayout lr
        }
    }
}

Mermaid and PlantUML are text but not models: each file is one diagram. Mermaid renders natively in GitHub, GitLab, many wikis and this course, and covers flowcharts, sequence, state and entity-relationship diagrams, with experimental C4 support. PlantUML is older and covers the UML set thoroughly; its C4-PlantUML library adds macros that apply the C4 notation for you, legend included:

@startuml
!include <C4/C4_Context>
title System context diagram — Financial Risk System
Person(user, "Business User", "Reads the daily risk reports")
System(frs, "Financial Risk System", "Calculates end-of-day risk")
System_Ext(tds, "Trade Data System", "System of record for trades")
Rel(user, frs, "Views risk reports using", "HTTPS")
Rel(frs, tds, "Gets trade data from", "Nightly file export")
SHOW_LEGEND()
@enduml

A second diagram that shows the Trade Data System has to declare it again — the price of one diagram per file. D2 is a newer text-diagram language in the same family.

Whatever the tool, text buys you diagrams versioned beside the code, changes reviewed as diffs in pull requests, no lost source files, and rendering in CI. It costs you control over layout — auto-layout will happily break the hygiene rules below — and it shuts out stakeholders who would edit a drawing but not a text file.

Model repositories. At enterprise scale the model moves into a repository, usually in ArchiMate: Archi (free and open source), Sparx Enterprise Architect, and several commercial repository products. The repository holds elements and relationships across the business, application and technology layers, and every diagram is a view onto it. It beats drawing when:

  • many people maintain many views over years, and the elements outlive any single project
  • you need impact analysis — "which business processes stop if the patient identity service is down?" — which is a query on a model and guesswork on a set of pictures
  • the organisation already keeps one: then your solution belongs in the repository, not in drawings beside it

The costs are real: a metamodel everyone must learn, tool licences, and a repository that rots without an owner. For one solution in one bid, it is usually overkill.

SituationReach for
A whiteboard session or a one-off explanationA sketch with a key
A handful of diagrams kept with the codeMermaid or PlantUML
Several C4 views of the same elements that must stay consistentStructurizr DSL
An enterprise estate, impact analysis, years of maintenanceAn ArchiMate repository
A proposal read by non-technical evaluatorsA polished drawing, exported from the model if you have one

Diagram hygiene

When tidying up a diagram, think about:

  • Aligning elements — either by one of their sides (e.g. top) or by their centres; the latter works best when aligning vertically
  • Making elements the same size where possible
  • Always including a key

A few further named rules round out the discipline: Less is more (an overloaded diagram with too many elements conveys less than a small, focused one, since the audience cannot tell what to focus on and disengages), No crossings (avoid letting any two connector lines cross), and Orthogonality (restrict connectors to strictly horizontal or vertical segments with right-angle bends, which instantly makes a diagram look more professional). A further rule, Hierarchies, requires that generalisation or realisation relationships be drawn with parent elements above their children so inheritance arrows consistently point upward.

One more, which C4's levels exist to enforce: one level of abstraction per diagram. Systems sit with systems and containers with containers. A server or a class on a container diagram is a sign that two diagrams have been merged into one.

Check yourself

  1. Your context diagram has an arrow from the platform to the referral management system labelled "uses". What is missing, and why does it matter for Lumen?
  2. What makes something a container in C4? Why is a notification service a container, while the email-template renderer inside it is probably not?
  3. A colleague puts the load balancer, the database servers and the three portals on the container diagram. Which rule is broken, and where do the servers belong?
  4. Which diagram would you draw for each: (a) the appointment stages Requested → … → Billed; (b) how the referral desk books manually today; (c) what happens when a patient accepts an offer?
  5. Name two things the offer-to-booking sequence diagram reveals that a container diagram cannot.
  6. Why does a model keep several views consistent when a set of drawings does not?
  7. A six-person team owns one product and keeps its documentation in the repository. Mermaid, Structurizr DSL or an ArchiMate repository — and why?
  8. Critics say C4 forces technology choices too early. Is that fair, and what do you do about it in a proposal?

Suggested answers

  1. The intent (what flows: new referrals, amendments, cancellations), the mechanism (a change extract every 15 minutes, with no events) and a stated direction convention. The mechanism matters because it bounds the referral-sync requirement: a polling platform can never be fresher than the extract interval.
  2. A container is something that must be running for the system to work — an application or a data store, deployed on its own. The template renderer is a grouping of code that runs inside the notification service and is not deployed separately, so it is a component.
  3. One level of abstraction per diagram. Load balancers and servers are infrastructure and belong on a deployment diagram; the container diagram shows the runnable units and how they communicate.
  4. (a) A state machine, because it is the lifecycle of one entity. (b) BPMN or a swimlane activity diagram, because it is work handed between roles. (c) A sequence diagram (or C4 dynamic diagram), because it is ordered interaction between a few participants, including waiting and failure.
  5. Any two of: the patient waits on the partner API, so its latency sits inside the 2-second budget; which calls are synchronous and which asynchronous; the slot-taken branch and where the referral goes after it; the point at which the stage becomes Confirmed; the need for an idempotency key when retrying.
  6. In a model each element exists once and every view refers to it, so a rename or deletion reaches every view. Drawings copy the element into each picture, and nothing checks that the copies still agree.
  7. Mermaid while they need a few independent diagrams; Structurizr DSL once several C4 views share elements and drift starts to cost them. An ArchiMate repository pays off across an enterprise estate that needs impact analysis, not for one product.
  8. Partly: container diagrams expect a technology on every box. In a proposal, mark undecided technologies as candidates or "to be decided in discovery", record each choice as a decision when it is made (Module 6, ADRs), and keep the rest of the notation rules.

Exercises — Module 5

Task. Draw two diagrams for Lumen Diagnostics: a system context diagram with the scheduling platform at the centre, and a container diagram of the platform, in C4 or any notation that meets the C4 notation rules. Output: two diagrams of one page each, each with a title and a key, plus a half-page list of the assumptions behind them. Time: about 2 hours. Inputs: the case; your Module 2 stakeholder register (the people on the context diagram); your Module 3 ASRs (a connector that carries a requirement, such as TLS 1.3 or the 15-minute referral sync, should say so); and your Module 4 decisions on search, the offer workflow and partner integration, which decide your containers. You will reuse both diagrams in the Module 6 SAD.

  • Draw a context diagram (scheduling platform at the centre)
    • Referral management system, patient identity service, SSO
    • The one automated partner API
    • Patients, referral desk, Scheduling Manager, partner practices, centre staff
    • The two open questions in the case — how Lumen's own centres publish availability, and how Billed reaches finance — shown as assumptions, not left out silently
  • Draw a container diagram of the platform
    • Portals, offer/workflow service, search, notifications, data stores
    • Apply the diagram-hygiene rules from this module
  • Label each connector with its intent and the protocol or data, not just "uses"
  • Optional: a sequence diagram for one run of the 15-minute referral sync, in the style of the booking flow above

Self-assessment

CriterionWhat good looks like
A key on each diagramEvery shape, line style, colour and arrowhead you used is explained, and the key says whether arrows show dependency or data flow
Every connector labelledEach connector carries its intent and the protocol or data, with the arrow pointing the way the label reads. No connector says only "uses"
Element types distinguishableA reader can tell people, the platform, its containers, data stores and external systems apart by shape or label, not by colour alone
External systems from the case all presentReferral management system, patient identity service, SSO and the automated partner group's API all appear, plus whatever you chose for email and SMS, with the two open questions marked as assumptions
No crossing linesNo two connectors cross. If they have to, the diagram is overloaded and should be split
One level of abstraction per diagramThe context diagram shows no containers; the container diagram shows no servers, classes or code modules