The lost art of

software design

Simon Brown
@simonbrown
Over the past decade, many
teams have thrown away
big design up front

@simonbrown
Unfortunately, architectural
thinking, documentation,
diagramming and modelling
were also often discarded

@simonbrown
The Agile Manifesto
doesn’t say
“don’t do design” 🙄

@simonbrown
You can’t move fast
with 💩 code
@simonbrown
“ ”
Big design up front is dumb.
Doing no design up front
is even dumber.
Dave Thomas
Big Design Up Front

Evolutionary Design

@simonbrown
Evolutionary
architecture

@simonbrown
Evolutionary architecture
Architecting for change also results
in signi cant decisions being made!

@simonbrown
fi
Planned vs unplanned evolution
… both need to be guided

@simonbrown
 Goals
1. Explain why some up front design is useful
2. Provide some tips on how to do design better

Some Design Up Front + Evolutionary Design

@simonbrown
 Product Technical
Design Design
Product vision, Technical vision,
UX, UI, A/B testing, technologies, modularity,
experimentation quality attributes,
business process, environmental constraints,
etc etc

I’m referring to technical design

rather than product design
@simonbrown
 Simon Brown
Independent consultant specialising in software architecture,
plus the creator of the C4 model and Structurizr

@simonbrown

@simonbrown
 Architecture meets agile
“we’re about to start our agile transformation … we need help
making our architecture/design processes more agile”

vs

Agile meets architecture

“we’ve been on our agile journey for X years … our software lacks
structure, we have no documentation, etc”
 Financial Risk System 3. Non-functional Requirements
a. Performance
• Risk reports must be generated before 9am the following business day in Singapore.
1. Context b. Scalability
A global investment bank based in London, New York and Singapore trades (buys and sells) financial products with • The system must be able to cope with trade volumes for the next 5 years.
other banks (“counterparties"). When share prices on the stock markets move up or down, the bank either makes • The Trade Data System export includes approximately 5000 trades now and it is anticipated that there
money or loses it. At the end of the working day, the bank needs to gain a view of how much risk of losing money will be slow but steady growth of 10 additional trades per day.
they are exposed to, by running some calculations on the data held about their trades. The bank has an existing • The Reference Data System export includes approximately 20,000 counterparties and growth will be
Trade Data System (TDS) and Reference Data System (RDS) but needs a new Risk System. negligible.
• There are 40-50 business users around the world that need access to the report.
1.1. Trade Data System c. Availability
The Trade Data System maintains a store of all trades made by the bank. It is already configured to generate a file- • Risk reports should be available to users 24x7, but a small amount of downtime (less than 30 minutes per
based XML export of trade data to a network share at the close of business at 5pm in New York. The export day) can be tolerated.
includes the following information for every trade made by the bank:
d. Failover
• Trade ID, Date, Current trade value in US dollars, Counterparty ID • Manual failover is sufficient, provided that the availability targets can be met.

e. Security
1.2. Reference Data System • This system must follow bank policy that states system access is restricted to authenticated and authorised
The Reference Data System stores all of the reference data needed by the bank. This includes information about users only.
counterparties (other banks). A file-based XML export is also generated to a network share at 5pm in New York, • Reports must only be distributed to authorised users.
and it includes some basic information about each counterparty. A new reference data system is due for • Only a subset of the authorised users are permitted to modify the parameters used in the risk calculations.
completion in the next 3 months, and the current system will eventually be decommissioned. The current data • Although desirable, there are no single sign-on requirements (e.g. integration with Active Directory, LDAP,
export includes: etc).
• All access to the system and reports will be within the confines of the bank’s global network.
• Counterparty ID, Name, Address, etc… f. Audit
• The following events must be recorded in the system audit logs:
• Report generation.
2. Functional Requirements • Modification of risk calculation parameters.

1. Import trade data from the Trade Data System. g. Fault Tolerance and Resilience
2. Import counterparty data from the Reference Data System. • The system should take appropriate steps to recover from an error if possible, but all errors should be
3. Join the two sets of data together, enriching the trade data with information about the counterparty. logged.
4. For each counterparty, calculate the risk that the bank is exposed to. • Errors preventing a counterparty risk calculation being completed should be logged and the process should
5. Generate a report that can be imported into Microsoft Excel containing the risk figures for all continue.
counterparties known by the bank.
h. Internationalization and Localization
6. Distribute the report to the business users before the start of the next trading day (9am) in Singapore.
7. Provide a way for a subset of the business users to configure and maintain the external parameters used • All user interfaces will be presented in English only.
by the risk calculations. • All reports will be presented in English only.
• All trading values and risk figures will be presented in US dollars only.

i. Monitoring and Management

• A Simple Network Management Protocol (SNMP) trap should be sent to the bank’s Central Monitoring
Service in the following circumstances:
• When there is a fatal error with the system.
• When reports have not been generated before 9am Singapore time.
j. Data Retention and Archiving
• Input files used in the risk calculation process must be retained for 1 year.
k. Interoperability
• Interfaces with existing data systems should conform to and use existing data formats.

“Financial Risk System” architecture kata “Financial Risk System” architecture kata
Simon Brown | @simonbrown Simon Brown | @simonbrown
 Design a software solution for
the ”Financial Risk System”, and
draw one or more architecture
diagrams to describe your solution

60-90 minutes
Iteration 1

@simonbrown
@simonbrown
Iteration 2

@simonbrown
@simonbrown
@simonbrown
“ ”
So you’re teaching teams
how to create nice diagrams?
Up Front Design
 #1

“Are we allowed
to do
up front design?”

@simonbrown
 #12

“We don't do up
front design
because we do
XP.”
@simonbrown
 #17

“It’s not expected

in agile.”

@simonbrown
“ ”
There is no Big Design Up Front. Most of the design activity
takes place on the y and incrementally, starting with "the
simplest thing that could possibly work" and adding complexity
only when it's required by failing tests.

https://en.wikipedia.org/wiki/Extreme_programming
fl
“ ”
What role does an architecture play when you are using evolutionary
design? Again XPs critics state that XP ignores architecture, that XP's route is
to go to code fast and trust that refactoring that will solve all design issues.
Interestingly they are right, and that may well be weakness. Certainly the
most aggressive XPers - Kent Beck, Ron Je ries, and Bob Martin - are
putting more and more energy into avoiding any up front architectural
design. Don't put in a database until you really know you'll need it. Work
with les rst and refactor the database in during a later iteration.

Martin Fowler
https://martinfowler.com/articles/designDead.html
fi
fi
ff
The “luminaries” in Agile are not telling people to do design either
(it’s easy to make assumptions about what's not being said)

@simonbrown
 Remember that the folks
behind the agile manifesto
have a lot of experience.

Most teams likely don’t have

that same level of experience.
@simonbrown
 Many people haven’t been
exposed to the problems that
agile was trying to solve

@simonbrown
@simonbrown
@simonbrown
@simonbrown
@simonbrown
 Agility requires a toolbox of
techniques and practices
but many people don’t have them,
and we’ve stopped teaching them

@simonbrown
How do you design software?

@simonbrown
“ ”
we use a whiteboard
“ ”
we draw boxes and lines
“ ”
the boxes
represent components
“ ”
we use our
experience
@simonbrown
@simonbrown
 CClCl
a s
a
las
s ss
o r a t o r s
C o l l a br a t o r s
s ll a b o
CCoollabo rs r a t o
R e s p onssi ib
b i il
l i it
t i ie
e
l s
i t i e s
Reesspopnonsibi
R

Class-Responsibility-Collaboration
@simonbrown
 Up front design is not
necessarily about creating a
perfect end-state or
complete architecture

@simonbrown
Evolutionary Design
Beginning With A Primitive Whole
@simonbrown
Evolutionary Design
Beginning With A Primitive Whole
@simonbrown
“ ”
Continuous attention to
technical excellence and
good design enhances agility.
Principle 9 of the Manifesto for Agile Software Development
A good architecture
enables agility

@simonbrown
 Enough up front design
to create a good
starting point and direction

@simonbrown
A starting point
adds value

@simonbrown
 Every team needs
technical leadership
(irrespective of team size)

@simonbrown
 Technical leadership exists at
multiple levels and dimensions
within most organisations
(from the enterprise perspective and platform teams; through to individual delivery teams,
irrespective of whether they have a system or service/capability focus)

@simonbrown
Incomprehensible software
architecture diagrams
UML?

@simonbrown
UML usage is low
@simonbrown
 #1

“I don’t know it.”

@simonbrown
 #36

“You’ll be seen as
old.”

@simonbrown
 #37

“You’ll be seen as
old-fashioned.”

@simonbrown
 #80

“It’s too detailed.”

@simonbrown
 #46

“We don’t want to

tell developers
what to do.”

@simonbrown
 #66

“The tooling
sucks.”

@simonbrown
 #92

“It’s not expected

in agile.”

@simonbrown
“ ”
Would it be better if we used a CASE tool to lay out the design?
No, it wouldn't. The design is more readily expressed, changed, and
understood when done less formally, with CRC or on the whiteboard
or a bar napkin.
Ron Je ries
https://ronje ries.com/xprog/articles/fussaboutdocumentation/
ff
ff
@simonbrown
@simonbrown
“just use a whiteboard”

@simonbrown
What’s wrong these diagrams?

@simonbrown
The perfection game
We rate the diagrams… (1-10)
We liked…
To make the diagrams perfect…

15 minutes
7
@simonbrown
7
@simonbrown
7
@simonbrown
7
@simonbrown
7
@simonbrown
7
@simonbrown
6
@simonbrown
/
7
10
@simonbrown
Swap and review your diagrams
1. Do the solutions satisfy the architectural drivers?
2. If you were the bank, would you buy this solution?

10 minutes
“ ”
It’s impossible to
answer those questions
If you can’t see and understand
a solution, you can’t evaluate it

@simonbrown
 #97

“The value is
in the
conversation.”

@simonbrown
“ ”
Now don’t get me wrong (again). You may well need some nicely formatted UML for your
project, or you may need to print out Javadoc when you distribute your code to other users, or
you may need to document the requirements for management or as part of a contract. If and
when you really need these things, then by all means you should do them. But inside your
collocated Whole Team, you most probably will not need them, because the information
you need will be communicated through the more e ective medium of conversation.

Ron Je ries
https://ronje ries.com/xprog/articles/fussaboutdocumentation/
ff
ff
ff
“ ”
They are all excellent, as long as there
is a conversation about their meaning
and intent. It's the accompanying
conversation that matters.
“the value is in the conversation”
only works if you’re having
the right conversations

@simonbrown
Super cial up front design
fi
 #4

“Is this a
microservices
architecture?”

@simonbrown
 #73

“Why is the ORM

directly connected
to the Angular
front-end?”
@simonbrown
 Why is the ORM
directly connected to
the Angular front-end?
@simonbrown
 #76

“Is the web UI

getting data from
Amazon S3?”

@simonbrown
If you don’t engage in the problem, you end up with
a very simpli ed and super cial view of the solution

@simonbrown
fi
fi
 A good architecture rarely
happens through
architecture-indi erent design

@simonbrown
ff
Part of the design activity is about
discovering “unknown unknowns”

@simonbrown
 Plateau

Accelerated learning

Slow initial progress

The typical s-curve of learning

@simonbrown
Technology Decisions
 The producer-consumer con ict
of software architecture diagrams

I don’t want to put I wish these diagrams

technology choices on included technology
the diagrams… choices…

Producer Consumer

fl
@simonbrown
 #8

“We don’t
solutionize.”

@simonbrown
 #10

“Our architects
are not allowed
to do
solutioneering.”
@simonbrown
 #39

“We don’t want to

impose a solution
upon the
development
team.”
@simonbrown
 #42

“We’re a Java team,

so it’s obviously
a Java solution.”

@simonbrown
How much up front design?
1. Is that what we’re going to build?

2. Is it going to work?
@simonbrown
We’re not trying to
make every decision

@simonbrown
“ ”
Architecture represents the
signi cant decisions, where signi cance
is measured by cost of change.
Grady Booch
fi
fi
 Programming languages

Architecture Technologies and platforms

Monolith, microservices or hybrid approach

Design

Implementation Curly braces on the same or next line

Whitespace vs tabs
@simonbrown
“ ”
I think there is a role for a broad starting point architecture. Such things
as stating early on how to layer the application, how you'll interact with the
database (if you need one), what approach to use to handle the web server.

Martin Fowler
https://martinfowler.com/articles/designDead.html
 “just use a whiteboard;
the value is in the conversation”

@simonbrown
@simonbrown
1. Is that what we’re going to build?

2. Is it going to work?
@simonbrown
Teams need a ubiquitous language
to communicate e ectively

@simonbrown
ff
A common set of abstractions
is more important
than a common notation
 The C4 model for visualising
software architecture
c4model.com

Zoom in

Zoom in

Zoom in

Level 1 Level 2 Level 3 Level 4

Context Containers Components Code
 Diagrams are maps
that help software developers navigate a large and/or complex codebase
@simonbrown
 Diagrams are maps
that help software developers navigate a large and/or complex codebase
@simonbrown
 Diagrams are maps
that help software developers navigate a large and/or complex codebase
@simonbrown
 Diagrams are maps
that help software developers navigate a large and/or complex codebase
@simonbrown
 Diagrams are maps
that help software developers navigate a large and/or complex codebase
@simonbrown
Diagrams are a visual checklist
for design decisions

@simonbrown
 System Context diagram
What is the scope of the software system we’re building?
Who is using it? What are they doing?
What system integrations does it need to support?

@simonbrown
@simonbrown
 Container diagram
What are the major technology building blocks?
What are their responsibilities?
How do they communicate?

@simonbrown
@simonbrown
The diagrams should spark
meaningful questions

@simonbrown
 No
“What does that arrow mean?”
“Why are some boxes red?”
“Is that a Java application?”
“Is that a monolithic application, or a collection of microservices?”
“How do the users get their reports?”

@simonbrown
 Yes
“What protocol are your two Java applications using
to communicate with each other?”
“Why do you have two separate C# applications instead of one?”
“Why are you using MongoDB?”
“Why are you using MySQL when our standard is Oracle?”
“Should we really build new applications with .NET Framework
rather than .NET Core?”

@simonbrown
 Richer diagrams lead to
richer design discussions

@simonbrown
 Richer diagrams lead to
better communication,
making it easier to scale teams

@simonbrown
The diagrams should provide
meaningful feedback

@simonbrown
“ ”
We’re trying to diagram a
[microservices|serverless] architecture,
but the diagram is getting complicated.
1. Is that what we’re going to build?

2. Is it going to work?
@simonbrown
“ ”
Base your architecture on
requirements, travel light
and prove your architecture
with concrete experiments.
Agile Architecture: Strategies for Scaling Agile Development
Scott Ambler
 Identify and mitigate
your highest priority risks

@simonbrown
 Like estimates,
risks are subjective

@simonbrown
 Risk-storming
A visual and collaborative technique for identifying risk

@simonbrown
Threat modelling
(STRIDE, LINDDUN, Attack Trees, etc)

@simonbrown
 “Architecture
Decision Record”
A short description of an
architecturally signi cant decision

http://thinkrelevance.com/blog/2011/11/15/documenting-
architecture-decisions (Michael Nygard)

@simonbrown
fi
How much up front design
should you do?

@simonbrown
Sometimes requirements are known,
and sometimes they aren’t
(enterprise software development vs product companies and startups)

@simonbrown
 #52

“I’m good with

maybe a day
for a one-year
e ort.”
@simonbrown
ff
Up front design is an iterative and
incremental process; stop when:

@simonbrown
Up front design is an iterative and
incremental process; stop when:
You understand the signi cant
architectural drivers (requirements,
quality attributes, constraints).

@simonbrown
fi
Up front design is an iterative and
incremental process; stop when:
You understand the signi cant
architectural drivers (requirements,
quality attributes, constraints).

You understand the context and scope

of what you’re building.

@simonbrown
fi
 Up front design is an iterative and
incremental process; stop when:
You understand the signi cant
architectural drivers (requirements,
quality attributes, constraints).

You understand the context and scope

of what you’re building.

You understand the

signi cant design decisions
(i.e. technology, modularity, etc).

@simonbrown
fi
fi
 Up front design is an iterative and
incremental process; stop when:
You understand the signi cant
You have a way to communicate your
architectural drivers (requirements,
technical vision to other people.
quality attributes, constraints).

You understand the context and scope

of what you’re building.

You understand the

signi cant design decisions
(i.e. technology, modularity, etc).

@simonbrown
fi
fi
 Up front design is an iterative and
incremental process; stop when:
You understand the signi cant
You have a way to communicate your
architectural drivers (requirements,
technical vision to other people.
quality attributes, constraints).

You understand the context and scope You are con dent that your design
of what you’re building. satis es the key architectural drivers.

You understand the

signi cant design decisions
(i.e. technology, modularity, etc).

@simonbrown
fi
fi
fi
fi
 Up front design is an iterative and
incremental process; stop when:
You understand the signi cant
You have a way to communicate your
architectural drivers (requirements,
technical vision to other people.
quality attributes, constraints).

You understand the context and scope You are con dent that your design
of what you’re building. satis es the key architectural drivers.

You understand the You have identi ed, and are

signi cant design decisions comfortable with, the risks associated
(i.e. technology, modularity, etc). with building the software.

@simonbrown
fi
fi
fi
fi
fi
 Up front design is an iterative and
incremental process; stop when:
You understand the signi cant
You have a way to communicate your
architectural drivers (requirements,
technical vision to other people.
quality attributes, constraints).

You understand the context and scope You are con dent that your design
of what you’re building. satis es the key architectural drivers.

You understand the You have identi ed, and are

signi cant design decisions comfortable with, the risks associated
(i.e. technology, modularity, etc). with building the software.

Techniques: Workshops, interviews, Event Storming, Impact Mapping, domain modelling, OOAD, CRC, DDD,
architecture reviews, ATAM, architecture dry runs, Risk-storming, concrete experiments, C4 model, ADRs, etc.

@simonbrown
fi
fi
fi
fi
fi
Some up front design to create a
starting point and direction
for further evolutionary design

@simonbrown
Adopt an agile mindset
Choose a starting point and continuously improve
to discover what works for you

@simonbrown
Thank you!

Simon Brown
@simonbrown