The document discusses service description, which is a software architecture document that visually diagrams components, dependencies, and communication using diagrams and text. It provides key details for understanding the problem and solution domains. The document recommends creating context, container, component, and deployment diagrams to illustrate the software architecture at different levels. These diagrams help technical and non-technical audiences understand the system. Sample diagrams are provided for each type to demonstrate how they can be used to visualize the architecture and answer common questions about the system. Maintaining an up-to-date service description is important to keep it relevant over time.

1. Visualizing
software architecture
effectively
in service description
Sanjoy Roy

2. What is service description?
A service description is a software architecture document with a
focus on software elements such as:
• component responsibilities, dependencies, communication
protocols, actors and functional characteristics
A service description can be a combination of both visual diagrams
and written text that provide just enough detail for understanding
what the actual problem domain is and how it's mapped to a solution
domain.

3. Service Description (cont.)
Think about the target audience.
 Who is going to read this document?
 What do they need to know?
 what are the design elements most important to illustrate?
Writing this document is not always one off activity.
It needs to be maintained to remain relevant.

4. Diagrams play very important role in service description.
Diagrams help to understand the software architecture.
Diagrams are the maps that help software developers
navigate a complex codebase.
Benefits of diagrams

5. Shared Vocabulary
Shared vocabulary makes sure everyone within the development
team communicates about their system in the same,
understood way.
It is important for a development team to have a shared
vocabulary before writing the service description.

6. A software system is made up of one or more
containers (web applications, mobile apps, standalone
applications, databases, file systems, etc.), each of
which contains one or more components, which in
turn are implemented by one or more classes.
Here is the shared vocabulary that I use

7. •A software system is the highest level of abstraction and
represents something that delivers value to its users,
whether they are human or not.
•A container represents something that hosts code or data.
A container is something that needs to be running in order
for the overall software system to work. Each container
should be a separately deployable thing.
•A component as simply being a grouping of related
functionality encapsulated behind a well-defined
interface.

8. Static Structure
Software System
Container Container Container
Component Component
Class Class Class
Component

9. Diagrams I draw in service description:
 Context Diagram
 Container Diagram
 Component Diagram
 Deployment Diagram
First three diagrams are based on Simon Brown’s C4 Model.
I don’t draw class diagram as suggested by C4 model.
But I draw sequence diagrams to show the logic flow.

10. Context Diagram
A context diagram defines
 what the system does and does not do
 where the boundaries are between it and the outside world
 how the system interacts with other systems,
organisations, and people across these boundaries.

11. A Context diagram helps to answer:
What is the
service that we
are building (or
have built) ?
Who is using it?
How does it fit in
with the existing
environment ?

12. Things to remember when drawing a context diagram:
Focus should be on
people (actors, roles,
personas, etc.) and
software systems rather
than technologies,
protocols, and other low-
level details.
Add a short description
of the person, software
systems, their roles and
responsibilities
Annotate every
interaction between
people and software
systems with some
information (purpose of
the interaction)
Target Audience:
Technical and
non-technical people

13. A Sample Context Diagram
Customer
Event Manager
[ Person ]
[ Person ]
ABC Customer
An event manager manages
events
Event Management System (EMS)
[ Software System ]
EMS manages event definition and its lifecycle
Views events
and buy tickets
Manages events

14. Container Diagram
The container diagram shows the high-level shape of the
software architecture and how responsibilities are distributed
across it.
It also shows the major technology choices and how the
containers communicate with one another.

15. What is the overall
shape of the
software system?
What are the high-
level technology
decisions?
How are the
responsibilities
distributed across
the system?
How do containers
communicate with
one another?
Where do I need to
write code in order
to implement
features?
A container diagram helps
you answer these
questions

16. Things to remember when drawing a container diagram:
For each container in the
diagram, show:
 the name of the container
 implementation technology
 a short description
Annotate the interactions between the containers
with:
 Purpose of the interaction
 Communication mechanism (REST, JMS, etc.)
 Communication style (sync, async, batch,
etc.)
 Protocols (HTTP, HTTPS, FTP, etc.)
Target Audience
Technical people (Developers,
Testers, Architects,
Operational & Support Staff)

17. A Sample Container Diagram
Customer
Event Manager
[ Person ]
[ Person ]
ABC Customer An event manager manages events
Event Management System (EMS) Boundary
Views events and buy tickets
Manages events
Uses
[ REST ]
[ HTTPS ]
Uses
[ REST ]
[ HTTPS ]
RDBMS
[Container: Oracle]
Stores event definition
WEB APPLICATION
[Container: Jetty]
Allows users to manage event
definition and its lifecycle
Reads from
and writes
data to
[ JDBC, port:
3306 ]

18. Component Diagram
• A component diagram shows the logical components that reside
inside each of the containers.
• This is useful because:
 It shows the high-level decomposition of the service into
components with distinct responsibilities
 It shows the relationships and dependencies between components
 It provides a framework for high-level software development
estimates and how the delivery can be broken down

19. A component diagram helps in answering the following questions:
What components
is the service made
of?
Is it clear how the
service works at a
high level?
Do all components
have a home (i.e.
reside in a
container)?

20. Things to remember when drawing a component diagram:
For each component in the
diagram, show:
 the name of the component
 implementation technology
 a short description
Annotate the interactions between the components
with:
 Purpose of the interaction (e.g. “uses”,
“persists data using”, “delegates to”, etc.)
 Communication style (e.g. synchronous,
asynchronous, etc.)
Target Audience
Technical people (Developers,
Testers, Architects,
Operational & Support Staff)

21. A Sample Component Diagram
Relational Database
[Container: Oracle]
Stores event definitions
Event Component
[Component: Spring Bean + Spring Data + JPA2 + Spring HATEOAS + Spring
Security + Spring MVC + Hibernate + JDBC]
Manages event’s definition and it’s lifecycle
Ticket Component
[Component: Spring Bean + Spring Data +
Hibernate + JDBC]
Manages ticket details
Logging Component
[Component: SLF4J + Logback]
Provides logging facilities to all
other components
Reads from and writes data to
[ SQL/JDBC, port 3306 ]
Associate events with
the tickets using
Used by all components
Customer Component
[Component: Spring Bean + Spring Data +
Hibernate + JDBC]
Manages customer details
Associate events with
the customers using

22. Deployment Diagram
• The deployment diagram describes the environment into
which the system will be deployed and the dependencies
that the system has on elements of it
• This diagram shows the physical environment in which the
system is intended to run, including the hardware or hosting
environment

23. Deployment Diagram
Things to remember when drawing a deployment diagram:
Try to capture clear, accurate,
detailed dependencies between
the software elements and the
runtime environment
Target Audience
Technical people (Developers,
Testers, Architects,
Operational & Support Staff)

24. Deployment View (cont.) – a sample deployment diagram
DMZ/Load Balancer
EMS EMS
HTTPS HTTPS
Firewall
HTTPS
HTTPS
BigIP
SpringBoot/Jetty/Java8 SpringBoot/Jetty/Java8
event-service.jar event-service.jar

25. Technical
Details
Context
Diagram
Container
Diagram
Component
Diagram
Deployment
Diagram

27. Think about the target audience

28. Reference
https://leanpub.com/visualising-software-architecture/read

29. Thank you.