VISUALISING SOFTWARE ARCHITURE

WITH C4 MODEL
WE HAVE A FAILURE TO COMMUNICATE
 What happened to SSADM, RUP, UML, etc?

• Past structured processes (e.g., RUP,

SSADM) provided valuable reference
points for software design.
• Despite the existence of UML, teams
often favor informal sketches, leading to a
loss of visual communication skills in the
race for agility.
• Typical software architecture diagrams
may lack clarity without detailed
narratives, posing challenges in
conveying design effectively.
SOME “EXAMPLES”
The shopping list

• The presented architecture diagram lacks

clarity, resembling a shopping list of
technologies.
• It features Unix and Windows boxes,
JBoss, and Microsoft SQL Server without
conveying their roles.
• There's a missing connection between
the Unix and Windows boxes, making it
more of a bulleted list presented as a
diagram.
Boxes and no lines

• The diagram depicts a three-tier solution

using the Microsoft technology stack.
• The top tier features an ASP.NET web
application, but lacks details on user
interaction.
• The middle tier consists of boxes representing
components or services, but lacks information
on responsibilities and interactions.
• The bottom tier is labeled "SQL Server" with
separate cylinders, leaving uncertainty about
whether they represent database servers,
schemas, or tables.
• The diagram is informative in illustrating the
decomposition of the middle tier but falls short
in providing the complete story, lacking both
responsibilities and interactions.
The “functional view”

• The diagram reflects a functional

decomposition approach commonly seen
in large organizations.
• It breaks down the solution into smaller
components without detailing
responsibilities or interactions.
• The addition of color coding introduces
ambiguity, leaving viewers to decipher its
meaning.
• Questions arise, such as the purpose of
color variations and the thickness of the
border on certain boxes.
• The diagram lacks clarity in conveying
meaningful information beyond a basic
functional breakdown.
The airline route map

• Overview:
• Favorite diagram in presentation.
• Sole visual aid for solution presentation.
• Diagram's Strengths:
• Central spine illustrates data flow from source systems
(TDS and RDS).
• Simple activity diagram outlining steps: data import,
calculations, report generation, distribution.
• Concerns and Confusion:
• Breakdown on the right: Unclear significance of the
green circle; clock implies scheduled events.
• Left side complexity: Overlapping lines, varied colors,
and styles.
• Upside-down "UI" letters: Result of individuals writing
from different positions around the table.
• Recommendations:
• Address ambiguity in the green circle and clock
elements.
• Simplify and clarify the left side of the diagram for better
understanding.
• Key Takeaway:
• Despite initial clarity, the diagram suffers from
communication breakdown due to unclear elements,
impacting overall comprehension.
 • Purpose:
•
Generically true
Ideal for quick and basic representation of software
architecture.
• Convenient for conveying an overview without delving into
specifics.
• Content Overview:
• Standard "Software Architecture 101" style.
• Generic labels like "transport," "archive," "audit," "report
generation," and "error handling."
• Central box labeled "business logic," lacking detailed
description.
• Strengths:
• Straightforward and easy to understand.
• Serves as a quick reference for software architecture
overview.
• Areas of Improvement:
• Lack of specificity in labels may lead to ambiguity.
• "Business logic" could benefit from more detailed
explanation or breakdown.
• Recommendations:
• Consider providing additional details in labeled boxes for
clearer understanding.
• Enhance the description of "business logic" for a more
informative representation.
• Key Message:
• While simplistic and suitable for a quick overview, further
detailing in specific areas would enhance clarity and
communication of the software architecture.
The “logical view”
• Type of Diagram:
• Logical, conceptual, or functional representation of software
system architecture.
• Content Overview:
• Illustrates the high-level building blocks of the software
system.
• Limited information beyond depicting the conceptual
structure.
• Purpose and Misconception:
• Intended to show logical relationships among components.
• Common misconception: Software architecture diagrams
should remain "logical" and avoid technology or
implementation details, especially pre-code development.
• Strengths:
• Provides a quick grasp of the conceptual structure of the
system.
• Limitations:
• Offers minimal information, lacks details about specific
functionalities or technologies.
• Future Considerations:
• Acknowledges the debate on whether to include technology
details in architectural diagrams.
• Key Takeaway:
• Useful for conveying the overall conceptual framework but
may require additional, detailed diagrams for a
comprehensive understanding of the software system's
architecture.
Deployment vs execution context

• Focus:
• Unix box, specifically "Risk Analysis System"
and "Data Import Service."
• Issue:
• Annotated as "JAR" (Java ARchive) but lacks
clarity on execution context.
• Ambiguity:
• Unix may not execute JAR files as standalone
applications without specific conditions.
• Recommendation:
• Clarify if "Risk Analysis System" and "Data
Import Service" operate as standalone
applications in the Unix environment.
• Key Message:
• Resolve ambiguity by specifying the execution
context for a more accurate depiction of
system behavior.
Homeless Old C# Object (HOCO)

• Components:
• C# console application and SQL Server
database identified.
• Uncertainty surrounds other C# components,
services, and modules.
• Ambiguity Source:
• Lack of clear boundaries or granularity
definition for various components.
• Proposal:
• Suggests enclosing most components within a
box to indicate their collective presence within
the C# console application.
• Objective:
• Provide clarity on whether components are at
the same level or part of the application.
• Key Message:
• Clarify boundaries by placing most
components within a designated box for a
clearer understanding of their role within the
C# console application.
 Common problems

• Notation inconsistencies (e.g., color • Consistency Challenges:

coding, shapes). – Notation inconsistencies (e.g., color coding,
• Ambiguity in purpose and meaning of line styles) persist between diagrams.
elements. – Element naming lacks uniformity across
diagrams.
• Missing or ambiguous relationships
• Logical Flow Issues:
between elements.
– Lack of clarity in the logical order for reading
• Use of generic terms like "business logic." the diagrams.
• Omission of technology choices or – Absence of a clear transition between
options. consecutive diagrams.
• Mixed levels of abstraction.
• Either too much or too little detail.
• Lack of context or logical starting point.
THE C4 MODEL
 C4 Model Overview

• 1. System Context:
– Overview of how the software system interacts with its external environment.
– Provides a high-level perspective of the system's place in the broader context.
• 2. Containers:
– Zooms into the software system, highlighting high-level technical building blocks (containers).
– Illustrates interactions between containers to understand the system's architecture.
• 3. Components:
– Focuses on an individual container, showcasing the internal components.
– Provides a detailed look at the structure within specific containers.
• 4. Code (UML Class) Diagram:
– Zooms into an individual component, revealing the implementation details.
– Visualizes the relationships and structure of code components within the system.
Hierarchical maps of your code

• C4 Diagrams: A Hierarchical Map for

Software Systems
– Conceptualize C4 diagrams as maps for
understanding software systems.
– Enables zooming in and out to varying levels
of detail, akin to navigating through maps.
• Shneiderman’s Mantra and C4:
– Shneiderman’s mantra, a simple concept for
data visualization, aligns seamlessly with the
C4 model.
– Both are hierarchical, facilitating the
comprehension and visualization of large
data sets.
 System Context and Containers: Overview first

System Context Diagram: Container Diagram:

–Starting point for –Follows the System Context
comprehending any software Diagram, delving into the
system. system's internals.
–Rapidly outlines system –Illustrates containers (web
scope, user base, and crucial apps, mobile apps, databases,
dependencies. etc.).
–Reveals the system's overall
–Quick to create and grasp, structure, distribution of
offering an immediate responsibilities, and major
overview. technology selections.
 Components: Zoom and filter

Zooming into Containers:

–Developers often require deeper insights, prompting a closer look
at each significant container.
–The focus shifts to revealing the internal components of each
container.
Components Diagram:
–Illustrates the decomposition of applications into components.
–Highlights key responsibilities and technology choices for each
component.
–Offers detailed insights into the internal structure of the software
system.
 Code: Details on demand

• Optional progression into deeper hierarchy for code-level exploration.

• Code-level elements include classes, interfaces, objects, functions, etc.
• Emphasizes that ultimate code detail resides within the actual codebase.
• Developers have the capability to access code-level details on-demand through
Integrated Development Environments (IDEs).
 Different diagrams, different stories

• Approach to Software Architecture Diagrams:

– Follow Shneiderman's mantra: Start at the top and progress into detail.
– Create a cohesive story, gradually delving deeper into the system's intricacies.
• Use of C4 Model:
– C4 model serves as a tool for describing the static structure of a software system.
– Not a design process but a collection of diagrams aiding in system understanding.
• Tailored Storytelling for Different Audiences:
– Different diagram levels allow tailoring stories for various audiences.
– Consider diverse technical backgrounds among the audience.
 Different diagrams, different stories (cnt.)

• Pragmatic Use of C4 Diagrams:

– C4 model includes four levels of abstraction.
– Not mandatory to create every diagram at each level.
– Recommend creating System Context and Container diagrams for all teams.
– Suggest thoughtful consideration of benefits versus costs for Component and Code diagrams.
• Efficiency in Diagram Creation:
– Highlight the importance of evaluating the utility of Component and Code diagrams.
– Emphasize the need to assess the value they provide compared to the effort required for creation
and maintenance.
LEVEL 1: SYSTEM CONTEXT DIAGRAM
 LEVEL 1: SYSTEM CONTEXT DIAGRAM

Intent Motivation
A System Context diagram helps you to answer the • Clearly defines system context and scope.
following questions.
1. What is the software system that we are building (or • Eliminates assumptions for a clear overview.
have built)? • Serves as a starting point, identifying stakeholders and
2. Who is using it? facilitating efficient requirements gathering.
3. How does it fit in with the existing environment?

Audience Required or optional?

• Technical / Non-technical people All software systems should have a System Context
• Inside or outside the software development team diagram.
STRUCTURE

• Central box represents your software

system.
• Surrounding the system are users
(Personal Customers) and external
software systems.
• Focus on actors, roles, and personas,
avoiding low-level technical details.
• Example: Internet Banking System -
Users access accounts and make
payments.
• Interaction with Mainframe Banking
System for core functions and Email
System for communication.
ELEMENTS - PEOPLE

• Identify users with names (individuals,

roles, actors, or personas).
• Include brief descriptions of their roles
and responsibilities.
• Capture essential information for each
profile:
– Name: Name of the person, user, role, actor,
or persona.
– Description: Short description outlining their
role and responsibilities.
ELEMENTS – SOFTWARE SYSTEMS

• Highlight other software systems outside

your system's scope.
• Emphasize lack of ownership and
responsibility for these external systems.
• Example: Internet Banking System
depends on the Mainframe Banking
System and E-mail System.
• Capture essential information for each
external system:
– Name: The name of the software system.
– Description: Brief overview of the software
system and its responsibilities.
ELEMENTS – ENTERPRISE BOUNDARY

• Illustrate organizational/enterprise
boundary with a dashed line.
• Show interactions between your system
and entities outside the boundary.
• Example: Dashed line represents the
bank's boundary.
• Capture contextual information about
location:
– Inside the boundary: Your software system
and internal entities.
– Outside the boundary: External software
systems and users.
– Emphasize interactions across the boundary.
LEVEL 2 : CONTAINER DIAGRAM
 LEVEL 2: CONTAINER DIAGRAM

Intent Motivation
• Container diagram illustrates high-level software • Opens up software system, revealing internal
architecture. components.
• Highlights distribution of responsibilities and major • Advantages:
technology choices. • Explicit high-level technology choices.
• Addresses key questions for developers and • Illustrates container relationships and
support/operations staff: communication.
• Overall shape of the software system. • Avoids clutter, serving as an intermediate step before
• High-level technology decisions. detailed Component diagrams.
• Distribution of responsibilities.
• Communication channels between containers. Required or optional?
• Development focus areas for implementing All software systems should have a Container diagram.
features.

Audience
• Targets technical professionals, from developers to
support staff.
STRUCTURE
• Internet Banking System comprises five
containers: Web App, Single-Page App,
Mobile App, API, and Database.
– Web App: Java/Spring MVC serving static
content; includes Single-Page App.
– Single-Page App: Angular application in
customer's browser, offering all banking
features.
– Mobile App: Cross-platform Xamarin app for
subset of functions.
– JSON/HTTPS API connects Single-Page App
and Mobile App to server-side Java/Spring MVC
App.
– API App interacts with Database (relational
schema) and Mainframe Banking System
(XML/HTTPS).
• Uses existing E-mail System for
customer emails.
• Physical instances, failover, clustering
details covered in separate Deployment
diagram.
ELEMENTS - CONTAINERS

• Each container represents an application or

data store.
• Information to capture for each container:
• Name: Container's name (e.g., "Internet-
facing web server," "Database").
• Technology: Implementation technology
(e.g., Java/Spring MVC, ASP.NET, Relational
Database Schema).
• Description: Brief statement of key
responsibilities or entities stored.
• If uncertain about technology, mention short-
list or general type.
• For standard RDBMS without proprietary
features, specify technology on deployment
diagram.
• Specify technology if container relies on
specific features of the RDBMS.
SOFTWARE SYSTEM BOUNDARY

• Draw a bounding box around containers

to show the system boundary.
• Corresponds with the single box in the
System Context diagram.
• Enhances clarity by visually emphasizing
the extent of the software system.
LEVEL 3: COMPONENT DIAGRAM
 LEVEL 3: CONTAINER DIAGRAM

Intent
Audience
Component diagram addresses key questions:
• Technical people within the software development
1. Identifies components within each container. team.
2. Ensures all components have a designated container.
3. Provides clarity on high-level software workings.

Motivation Required or optional?

• Illustrates high-level container decomposition into • Component diagrams are not typically drawn for data
components. storage containers or simple containers (e.g.,
• Highlights relationships and dependencies between microservices).
components. • Monolithic applications may benefit from Component
• Summarizes implementation details, frameworks, and diagrams during upfront design.
libraries in use. • In real-world use, teams often view this level of detail
• Serves as a valuable tool for understanding codebase as optional due to effort and maintenance challenges.
structure when components align with code mapping. • High component count may lead to clutter; strategies
for managing complexity will be discussed later.
STRUCTURE

• Architecture diagrams often depict

components in a software system.
• Component diagram here focuses on
components within a single container.
• Example: Internet Banking System's API
Application with Spring MVC Rest
Controllers.
• Illustrates division of API into
components, responsibilities, and
technology details.
ELEMENTS - COMPONENTS

• Components are coarse-grained building

blocks within a container.
• Information to capture for each
component:
• Name: Component's name.
• Technology: Implementation technology
(e.g., Plain Old [Java|C#|Ruby|etc] Object,
EJB, WCF service).
• Description: Brief sentence outlining the
component's responsibilities.
• Component identification is independent
of code packaging and architectural style.
• Component diagram should reflect the
architectural style in use (layered,
hexagonal, etc.).
CONTAINER BOUNDARY

• Include people, software systems,

and containers in the Component
diagram.
• Recommend drawing a bounding
box to explicitly show the container
boundary.
• Enhances clarity by visually
indicating the scope of the
container within the diagram.
LEVEL 4: CODE-LEVEL DIAGRAM
 LEVEL 4: CODE-LEVEL DIAGRAM

Intent
Audience
Code-level diagrams aim to illustrate code structure,
• Technical people within the software development
showcasing component implementation details.
team, specifically software devel

Motivation Required or optional?

• Code-level diagrams bridge high-level, coarse-grained • Code-level detail resides in the code, accessible to
components to real-world code elements. developers on demand.
• Aims to connect the worlds of software architecture • Optional level of detail; generally not recommended.
and code for a comprehensive understanding. • Class diagrams reserved for complex components or
to describe widely used patterns in a codebase.
STRUCTURE

• For object-oriented languages, UML class

diagrams are effective.
• Generate automatically from code or
draw freehand.
• Example: Zooming in on "Mainframe
Banking System Facade" within the "API
Application" container in the Internet
Banking System.
Class Diagram
Class Diagram
Class Diagram
Activity Diagrams And Sequence Diagrams
 Case Study - Design a Hotel Management System

1. The system should support the booking of different room types like standard, deluxe,
family suite, etc.
2. Guests should be able to search the room inventory and book any available room.
3. The system should be able to retrieve information, such as who booked a particular
room, or what rooms were booked by a specific customer.
4. The system should allow customers to cancel their booking - and provide them with
a full refund if the cancelation occurs before 24 hours of the check-in date.
5. The system should be able to send notifications whenever the booking is nearing the
check-in or check-out date.
6. The system should maintain a room housekeeping log to keep track of all
housekeeping tasks.
7. Any customer should be able to add room services and food items.
8. Customers can ask for different amenities.
9. The customers should be able to pay their bills through credit card, check or cash
 Class Diagram

• Hotel and HotelLocation: Our system will support multiple locations

of a hotel.
• Room: The basic building block of the system. Every room will be
uniquely identified by the room number. Each Room will have
attributes like Room Style, Booking Price, etc.
• Account: We will have different types of accounts in the system:
one will be a guest to search and book rooms, another will be a
receptionist. Housekeeping will keep track of the housekeeping
records of a room, and a Server will handle room service.
• RoomBooking: This class will be responsible for managing
bookings for a room.
• Notification: Will take care of sending notifications to guests.
• RoomHouseKeeping: To keep track of all housekeeping records for
rooms.
• RoomCharge: Encapsulates the details about different types of
room services that guests have requested.
• Invoice: Contains different invoice-items for every charge against
the room.
• RoomKey: Each room can be assigned an electronic key card. Keys
will have a barcode and will be uniquely identified by a key-ID.
 Case Study - Design a Library Management System

1. Any library member should be able to search books by their title, author, subject category as well
by the publication date.
2. Each book will have a unique identification number and other details including a rack number
which will help to physically locate the book.
3. There could be more than one copy of a book, and library members should be able to check-out
and reserve any copy. We will call each copy of a book, a book item.
4. The system should be able to retrieve information like who took a particular book or what are the
books checked-out by a specific library member.
5. There should be a maximum limit (5) on how many books a member can check-out.
6. There should be a maximum limit (10) on how many days a member can keep a book.
7. The system should be able to collect fines for books returned after the due date.
8. Members should be able to reserve books that are not currently available.
9. The system should be able to send notifications whenever the reserved books become available,
as well as when the book is not returned within the due date.
10.Each book and member card will have a unique barcode. The system will be able to read
barcodes from books and members’ library cards.
 Class Diagram

• Library: The central part of the organization for which this software has
been designed. It has attributes like ‘Name’ to distinguish it from any
other libraries and ‘Address’ to describe its location.
• Book: The basic building block of the system. Every book will have
ISBN, Title, Subject, Publishers, etc.
• BookItem: Any book can have multiple copies, each copy will be
considered a book item in our system. Each book item will have a unique
barcode.
• Account: We will have two types of accounts in the system, one will be a
general member, and the other will be a librarian.
• LibraryCard: Each library user will be issued a library card, which will be
used to identify users while issuing or returning books.
• BookReservation: Responsible for managing reservations against book
items.
• BookLending: Manage the checking-out of book items.
• Catalog: Catalogs contain list of books sorted on certain criteria. Our
system will support searching through four catalogs: Title, Author,
Subject, and Publish-date.
• Fine: This class will be responsible for calculating and collecting fines
from library members.
• Author: This class will encapsulate a book author.
• Rack: Books will be placed on racks. Each rack will be identified by a
rack number and will have a location identifier to describe the physical
location of the rack in the library.
• Notification: This class will take care of sending notifications to library
members.
 Case Study – Design an ATM

• The main components of the ATM that will • The user can have two types of accounts:
affect interactions between the ATM and its 1) Checking, and 2) Savings, and should
users are:
be able to perform the following five
1. Card reader: to read the users’ ATM cards.
transactions on the ATM:
2. Keypad: to enter information into the ATM
e.g. PIN. cards. 1. Balance inquiry: To see the amount of
3. Screen: to display messages to the users. funds in each account.
4. Cash dispenser: for dispensing cash. 2. Deposit cash: To deposit cash.
5. Deposit slot: For users to deposit cash or 3. Deposit check: To deposit checks.
checks.
6. Printer: for printing receipts. 4. Withdraw cash: To withdraw money from
7. Communication/Network Infrastructure: it their checking account.
is assumed that the ATM has a 5. Transfer funds: To transfer funds to
communication infrastructure to communicate another account.
with the bank upon any transaction or activity.
 Class Diagram

ATM: The main part of the system for which this software has been designed.
It has attributes like ‘atmID’ to distinguish it from other available ATMs, and
‘location’ which defines the physical address of the ATM.
CardReader: To encapsulate the ATM’s card reader used for user
authentication.
CashDispenser: To encapsulate the ATM component which will dispense
cash.
Keypad: The user will use the ATM’s keypad to enter their PIN or amounts.
Screen: Users will be shown all messages on the screen and they will select
different transactions by touching the screen.
Printer: To print receipts.
DepositSlot: User can deposit checks or cash through the deposit slot.
Bank: To encapsulate the bank which ownns the ATM. The bank will hold all
the account information and the ATM will communicate with the bank to
perform customer transactions.
Account: We’ll have two types of accounts in the system: 1)Checking and
2)Saving.
Customer: This class will encapsulate the ATM’s customer. It will have the
customer’s basic information like name, email, etc.
Card: Encapsulating the ATM card that the customer will use to authenticate
themselves. Each customer can have one card.
Transaction: Encapsulating all transactions that the customer can perform
on the ATM, like BalanceInquiry, Deposit, Withdraw, etc.
MORE EXAMPLES
System Landscape diagram

• System Context: Focuses on direct

relationships with the software
system.
• System Landscape: Depicts a
broader IT landscape to convey a
larger story.
• Utilizes a dashed box for the
enterprise boundary and distinct
element styles for internal and
external entities.
Microservices Architecture

• Microservices architecture example

with a message bus broadcasting
"customer update event" to
Reporting and Audit services.
• Numbering lines for clarity, with the
option for nested sequence
numbering (e.g., "5.1") for
precision.
• Preference for collaboration
diagram due to ease of drawing,
but both types work.
• Tips on notation from earlier
discussions remain applicable.