Communicating Software Architecture using Arc42 v1.1

1
Communicating Software
Architecture
Using
Prepared by:
Ashraf Fouad Ayoub
V1.1, 15-Nov-2025

2
Trademarks
• Arc42 within the meaning of these GTC is a civil law partnership of Dr. Peter Hruschka and Dr. Gernot Starke.
• UML® is a registered trademark, and BMM™, BPMN™, Business Motivation Model™, Business Process Modeling Notation™, and Unified
Modeling Language™ are trademarks of Object Management Group, Inc. in the United States and/or other countries.
• All other brand, company, and product names are used for identification purposes only and may be trademarks that are the sole property of
their respective owners.

3
Disclaimer
• Infographics included in this presentation based on licensed version from Infograpia.
• Free logos & icons from website: SVG REPO , Text Studio.

Target Audience / Expected Outcomes
Senior
Developers /
Software Team
Leaders
Communicate Architecture Decisions Clearly
Use Notation and Tools Effectively
Apply View-Based Documentation Approach
Tailor Communication to Stakeholders
Understanding the Purpose & Benefits
Quickly Onboard newly joined team member

Dr. Gernot Starke
Software Architecture & Engineering
LinkedIn Profile
Official Website
Books
Several books listed on personal website
Special Thanks
(Co-) founder of arc42
The template for communication and documentation of
software architectures.
Founder of aim42
Founder of aim42, the architecture improvement method.
Aim42 supports the systematic improvement,
modernization, and renovation of existing systems.
(Co-) founder of iSAQB
Non-profit association for the establishment and
standardization of the training of software architects.
Arc42 by Example, 3rd
edition

6
1
2
Introduction
Documentation Hierarchy – arc42
Agenda
3 FAQ

7
1- Introduction
Why arc42?
Documentation frameworks
Why?
What is Software Architecture Documentation?

8
Software Architecture Documentation
• Defn: “Software Architecture is the
fundamental concepts or properties
of a system in its environment
embodied in its elements,
relationships, and in the principles
of its design and evolution.”
Source[2] Principles of technical documentation
Source[3] ISO/IEC/IEEE 42010:2022 (Formerly
IEEE-1471)

9
Why it is so important?
Preserve
knowledge
Enhance knowledge
sharing
Decrease Mentor
time for onboarding
Improved
Communication
Faster onboarding time for
developers, architects, & LLMs
Cost
Saving
Development
Consistency
Improved
Maintainability
Reduced
Troubleshooting time
Reduced
Downtime
Minimize
rework
Foundation for scaling
and modernization
Compliance
Necessity
Decision
Justification

10
Some Documentation Frameworks
1995
“4+1”
View
Model
1998
IEEE
1016
SSD
1987
IEEE
1016
SSD
2009
IEEE
1016
SSD
2020
Inactive
Views &
Beyond
Addison
-Wesley
2002
Views &
Beyond
Addison
-Wesley
2010 2012
Software
Engineer
ing in
Practice
Software
Engineer
ing in
Practice
2021
2005
1st
Edition
2025
9th
Edition

11
What is Common Across Frameworks?
Multiple views are
required to show the
architecture.
Source [8] Types Of Building Plans Pdf, Free Printable.

Diagraming is a skill
Diagraming is a skill that can be acquired and developed by anyone,
not just artists or designers or architects.
Book
amazon.com (Rating: 4.4)
ISBN: 978-1098140502
Also, tools can help too: (Text to Diagrams) (Text to UML)
Some tools already have AI capabilities to make it even easier for this
generation.
D2: Declarative Diagramming
A modern language that turns text to diagrams

13
Why ?
1. Open Source.
2. Compact, lean, lightweight & concise.
3. Practical and field-proven standard, applied
successfully across industries including Fintech,
Telecom, & public sector.
4. Process and Technology neutral.
5. Optimized for clarity and communication.
6. Facilitates sustainability and Maintainability.
7. Supported by iSAQB (International Software
Architecture Qualification Board), supports
education and training.
8. Easily integrated with other models, notations (C4
model, UML, ADR, … etc).
9. 35 examples, 144 tips how to use the template.
Sample 43 pages for CRM project of 2000+ Developer days

15
2- Documentation Hierarchy – arc42
Documentation Hierarchy:
1- Introduction & Goals.
2- Constraints.
3- Context & Scope.
4- Solution Strategy.
5- Building Block View.
6- Runtime View.
7- Deployment View.
8- Crosscutting Concepts.
9- Architectural Decisions.
10- Quality Requirements.
11- Risks & Technical debts.
12- Glossary.

16
Documentation Hierarchy
• Four views.
• Plus, cross-cutting concepts (Ex: Logging, security,
… etc).
• Arc42 Template Overview (Online).

17
1-Introduction and Goals (1/3)
1.1 Introduction & Goals
• Required Functions: ASR.
Architecturally
Significant
Requirements

18
1- Introduction and Goals (2/3)
1.2 Quality Goals
• Quality goals: There are many non-functional requirements (
Wikipedia: List of system quality attributes), most architecture will select 3 – 5 maximum.
• Most known or referenced quality attributes:
Source [9]: ISO/IEC 25010, the product quality model.
Source [10]:
Developer To Architect, Architecture Styles Worksheet

19
1- Introduction and Goals (3/3)
1.3 Stakeholders
Role Contact Expectation
Developers
Admin / Application Support
Solution / Enterprise Architect
Business Operation
UI/UX
Release Manager
Cybersecurity / Auditors
Which diagrams?
Status?
Reports?
Compliance?
Implementation
details?
?
?
?
?
?
?
?

20
2- Constraints
Constraint Type Description Consequence
Scope
Time
Cost
Quality
Risk
Benefits
Inspired from Source [11]
What are project constraints? How to manage for success!.

21
Neighbo
ur
(-system)
Exchanged data
(events,
products)
Description
OmniPrint Printing data postscript or pdf
OmniPrint Printing result JSON structure, delivered daily
UltraScan Client master data
excerpt
.....
3- Context & Scope (1/3)
• Notation:
• Boxes & arrows.
• C4Model.
context == system border
separates OUR code
from OTHER code

22
3- Context & Scope(2/3)
• Notations:
• Boxes, or UML.
• C4Model.

23
3- Context & Scope(3/3)
1. System scope and context delimits your system (i.e. your scope) from all its communication partners
(neighboring systems and users, i.e. the context of your system).
2. It thereby specifies the external interfaces (Inbound, Outbound).
3. If necessary, differentiate the business context (domain specific inputs and outputs) from the technical
context (channels, protocols, hardware).
4. All stakeholders should understand which data are exchanged with the environment of the system.
5. You must differentiate between your environment and external parties.
6. It is recommended to have component diagram for your system with appropriate interfaces.
7. Tips:
a. Start from day 1.
b. Collect feedback from all stakeholders.
c. If you have many systems you are interacting with, create clusters or categories.

24
4- Solution Strategy
Quality Goal Scenario Solution Approach
Availability
Fault Tolerant
1. A short summary and explanation of the fundamental decisions and solution strategies, that shape the
system’s architecture. These include
a. Technology decisions.
b. Decisions about the top-level decomposition of the system, e.g. usage of an architectural pattern or
design pattern.
c. Decisions on how to achieve key quality goals.
d. Relevant organizational decisions, e.g. selecting a development process or delegating certain tasks to
third parties.

25
5- Building Block View (1/4)
5.1 Level 1
• Notation: UML, or C4Model. Rationale
We used functional decomposition to separate responsibilities:
• CheckerCore shall encapsulate checking logic and Html
parsing/processing.
• all kinds of outputs (console, html-file, graphical) shall be handled
in a separate component (Reporter)
• Implementation of Gradle specific stuff shall be encapsulated.
Context
Level-1

26
5.2 Level 2
• Notation: UML, or C4Model.
Level-2
Level-1
Context

27
• Linking source code and building blocks.

28
1. Use tabular form to describe your blackbox building block.
Blackbox building block
Name Responsibility Doc Link
1. Use diagrams to explain building block.
2. Describe the motivation for this decomposition.
3. Detailed description of each component.
4. Describe important interfaces.
Whitebox building block

29
6- Runtime View
1. Explains systems’
dynamic (Order of
action, processes).
2. Notation: UML
a. Sequence.
b. Collaboration.
c. Activity.
d. Flowcharts.
e. Numbered list.

30
7- Deployment View (1/2)
7.1 Level 1
Sample source: Sparx Systems (Enterprise Architect)

31
7- Deployment View (2/2)
7.1 Level 2

32
8- Crosscutting Concepts
Suggested sequence:
1. Start with Patterns.
2. Under the hood.
3. Safety & Security.
4. Make sure to cover the operations &
administrations.
• Many of these concepts relate to or
influence several of your building blocks.

33
9- Architectural Decisions
1. There are multiple templates for ADR. Source [15]
joelparkerhenderson/architecture-decision-record
offers several templates for the ADR.
2. If you are new to ADR, recommended to view the
links [12], [13], [14].
Option 1
Title Title of the ADR
Context Context of ADR
PROS / CONS
PROS/CONS
for Option 1
PROS/CONS
For Option 2
PROS/CONS
For Option 3
Decision Final Decision after voting
Consequence
Consequence of the
decision
Status
Proposed/Approved/
Rejected
Option 2 Option 3
Stakeholders List of Stakeholders and their titles, and votes

34
10- Quality Requirements (1/2)
10.1 Quality Tree
Source [17] Q42 for ISO 25010 users
• The most important of these requirements have already been described in section
1.2. (quality goals), therefore they should only be referenced here. In this section
10 you should also capture quality requirements with lesser importance, which will
not create high risks when they are not fully achieved (but might be nice-to-have).

35
10- Quality Requirements (2/2)
10.2 Quality Scenarios
Quality Category Quality Description Scenario
Performance Efficiency Capacity
Optimal Resource Utilization: An efficient system avoids both over-provisioning (which leads to
unnecessary costs) and under-provisioning (which leads to performance bottlenecks, latency,
and service disruptions).
SC1
Example Quality tree
Scenario ID Scenario Name Source Stimulus Environment Artifact Response Response
Measure
SC1
Capacity
optimal
resource
utilization
Stress Testing
tool
Pumping MQ with
rate up to 1,000
TPS for a duration
of 30 mins
UAT Backend system
Process all
messages without
failure, each
message should be
within 500 ms and
number of
containers replicas
should not exceed 4
Example Scenarios

36
11- Risks and Technical Debts(1/2)
11.1 Risks
ID
Date
raised Description
Likelihood of
the risk
occurring
Impact if the
risk occurs Severity Owner Mitigation action Status
1 … Low High High … Active
2 … Medium Medium Medium … Resolved
3 … High Low Low … Monitoring
4 Escalated
5 Mitigated
6
Sample risk register

37
11- Risks and Technical Debts(2/2)
11.2 Technical Debts
ID
Date
raised
Description
Reason /
Dependency
Estimated time
to fix
Priority
Target fix
version
Referenc
e
Status
1 … Cost limitation 16 hrs High V3.2 In progress
2 … Medium V3.1 Done
3 … Low V3.6 Open
4
5
6
Sample technical debt register

38
12- Glossary
• Standard list of abbreviations and terms used in alphabetical order.
Abbreviation Definition
BPMN Business Process Modeling Notation
EA Enterprise Architecture / Enterprise Architect
PMO Project Management Office
REPO Repository
TCO Total Cost of Ownership
UML Unified Modeling Language

40
3- FAQ
1- LLD vs HLD.
2- Arc42 vs C4 vs ADR.
3- Context Diagram vs Threat Modeling.

41
1- LLD vs HLD
• Enterprise Architects
• Focus on strategy, roadmap, and governance.
• Ensures the right business problem is solved in the
right way.
Technical Perspective
Business
Perspective Source: Inspired from [19], [20]
Enterprise Architect
Global Business
Perspective
Solution Architect
Bridging the gap
between planning &
implementation
Software / Technical Architect
Dealing with Engineering Issues
• Solution Architects
• Focus on End-to-End Solution Delivery.
• Solves business problems, defined by business or user requirements.
• Focus on High Level Design (HLD).
• SAD (Solution Architecture Document), TTD (Technical Design Document).
• Ref 1: Based on “Solutions Architect's Handbook”.
• Ref 2: https://github.com/bflorat/architecture-document-template
• Software / Technical Architects
• Focus on delivery for specific technology/product.
• Ensures specific products are delivered on time and maintains
operation.
• Focus on Low Level Design (LLD).
Low High
Low
High

42
2- Arc42 vs C4 vs ADR(1/2)
• Comparison is not Apple to Apple:
• Arc42: is a template for architecture communication and documentation.
• C4Model: is an easy to learn, developer friendly approach to software architecture diagramming.
• ADR: is a document that describes a choice the team makes about a significant aspect of the software architecture they’re
planning to build (AWS), (Azure).
• C4 can be used as the notation / diagram in arc42 document various sections:
• Section 3: Context & Scope.
• Section 5: Building blocks.
• ADR is an important section in arc42.

43
2- Arc42 vs C4 vs ADR(2/2)
Source: Simon Brown - Software architecture
as a contributor to high performing teams (
Youtube: 21:38)
Source: Simon Brown - Software architecture as
a contributor to high performing teams (
Youtube: 22:45)

44
3- Context Diagram vs Threat Modeling
vs
Context Diagram Threat Modeling
Primary Focus
Typical Content
Main Goal
Target Audience
Security Analysis role
System boundaries, integrations,
environment
System as a black box, actors, data flows
Define system’s operational context
Business stakeholders, product owners,
project managers, developers, architects
Not designed for security assessment
Entry/exit points, trust boundaries, attack
surfaces
System/components, external actors,
trust boundaries, data flows
Identify system elements and interfaces to
assess possible risks
Security architects, software engineers,
compliance and risk professionals
Central to security analysis

45
Glossary of terms and abbreviations
Abbreviation Definition
ADR Architecture Decision Record
ASR Architecturally Significant Requirements
EA Enterprise Architecture / Enterprise Architect
IT Information Technology
ITPMO Information Technology Project Management Office
PMO Project Management Office
REPO Repository
SVG Scalable Vector Graphics
TCO Total Cost of Ownership
UML Unified Modeling Language

46
References(1/2)
[1] arc42 official website.
[2] Principles of technical documentation, Dr Gernot Starke, 22-Jan-2022.
[3] ISO/IEC/IEEE 42010:2022, ISO, Nov-2022.
[4] Architectural Blueprints — The “4+1” View Model of Software Architecture, Philippe Kruchten, Rational Software Corp (IBM), Nov-1995.
[5] IEEE Software Design Descriptions (SSD), 1987, 1998, 2009.
[6] Documenting Software Architectures: Views and Beyond, 1st
edition – 2002, 2nd
edition – 2010, Addison-Wesley Professional.
[7] Software Engineering in Practice, 3rd
-2012, 4th
- 2021, Addison-Wesley Professional.
[8] Types Of Building Plans Pdf, Free Printable.
[9] ISO/IEC 25010, the product quality model.
[10] Developer To Architect, Architecture Styles Worksheet, Mark Richards.
[11] What are project constraints? How to manage for success!, Sandeep Kashyap, October 30, 2024.
[12] ADRs: the lost art of documenting important architectural decisions, Marek Dominiak, May 15, 2024.
[13] Lesson 157 - Incorporating ADRs Into Existing Systems, Mark Richards, Mar 26, 2023.
[14] ADR process, AWS.
[15] joelparkerhenderson/architecture-decision-record, Joel Parker Henderson.

47
References(2/2)
[16] arc42 Quality Model.
[17] Q42 for ISO 25010 users.
[18] arc42 FAQ.
[19] Solution Architect: Processes, Role Description, Responsibilities, and Certifications, Altexsoft, 14-Apr-2022
[20] WHO IS SOLUTION ARCHITECT: SALARY AND RESPONSIBILITIES, Yuri Musienko, 17-Nov-2021.

Communicating Software Architecture using Arc42 v1.1

More Related Content

Similar to Communicating Software Architecture using Arc42 v1.1

More from Ashraf Fouad

Recently uploaded

Communicating Software Architecture using Arc42 v1.1