Software Architecture

Documenting architecture
BITS Pilani
Contents

• Introduction
• Different architectural views
• Combining different views
• Documentation package
Introduction

• Architectural documentation serves as a communication vehicle

between architects and stakeholders such as business managers,
sponsor, end users

• It forms the basis for system analysis and construction – to

analyse how well the architecture meets the quality attributes and to
plan the construction of different parts of the system
Different architectural views

• Architecture can be complex

• We may not be able to understand the system with just

one diagram

• We may need different types of diagrams to understand

different aspects such as structure and behaviour
Different views of human body

Blood
Skeletal view Digestive system circulation Nervous system
system
Different views of human body

Cavities of the body Detailed view of heart Detailed view of brain

3 types of architecture views

• Module view: Shows structure consisting of different modules and

sub-modules

• Component & Connector view: Shows how the different

components interact

• Allocation view: Shows where the components reside

Module view of ERP system

ERP system

Finance Marketing Production

Market
Accounting Budgeting Audit Advertising Planning Inventory
research
Module view of Judiciary
system

Judiciary
system

Business Technical
modules modules

Proceedin Schedulin Judgemen

Case Evidences
gs g t

Data Workflow SMS

access engine Client
Module view: Air traffic control
system

Modules

&

Usage of modules by other

modules

Ref: ‘4+1 view’ by P. Kruchten

Module view - Uses

• It is a blue print for construction

• Change impact analysis
• Plan incremental development
• Requirement traceability
Module documentation –
Court Management System
Name: Proceedings

Responsibilities:
• Maintain information about proceedings of different cases
• Allows entry by court staff and verification by judge
• Can retrieve linked evidences and documents
• Logs changes

Interface
• Add proceedings (Case code, Date, Text)
• Verify proceedings (Case code, Date)
• Retrieve evidences (Case code) Returns List of evidences
Module documentation –
Another Example
Name: Inventory module

Responsibilities:
• Maintain information about items
• Handle inventory transactions
• Generate inventory analytics reports
• Automatically generate invoices when quality goes below reorder level

Interface
• Issue inventory (Item code, quantity) Returns Success or Error code
• Receive inventory (Item code, quantity) Returns Success or Error code
• Check quality (Item code) Returns quantity
Module documentation -
Examples
Name: Workflow engine

Responsibilities:
• Maintains workflow graph consisting of sequence of tasks for a process
• Maintains information about pending tasks
• Alerts users of their pending tasks

Interface
• Add task (Task name, Task description, Previous task name, User types
who can perform this task)
• Add task instance (Task name, Id of User who should perform this task)
returns Task Id
Component & Connector view

• Shows how components interact

• Components examples: Objects, processes, databases
• Connector examples: Method invocation, message,
protocols (HTTP)
C& C view: Example

Client PC Client PC Client PC

Retail banking Retail banking Retail banking
frontend frontend frontend
ODBC ODBC ODBC

LAN

DBMS Bank
DB
Backend Server

ODBC Open DataBase Connectivity API provided by DB vendor

C&C View: Example
Client Client
Browser Browser HTTPS

Firewall

Web server / App Server

Method invocation
Case Proceedings Evidences
Technical Business

mod. module module

services services

Scheduling Judgement
RESTful APIs
module module

Data access Workflow SMS gateway

SMS client
module engine (Telco)
Firewall
JDBC

Mirroring Encrypted passwords

C&C View: Example

Picking
module
New
Order order Message Transport
module queue module

Loyalty
module

The Order module informs other modules via a message queue

Using a Publish-Subscribe model
Component & Connector view

• Data access module – Database : JDBC

• SMS Client – SMS Gateway : REST
• Client – Webserver : HTTP
• Order module – Other modules : Message queue
C & C view: Uses

• Understand how system works

• Analyse reliability, performance, security, etc.

Examples:
• If SMS gateway is unreliable, introduce a reliable
message queue to put requests to SMS gateway. Let a
process keep trying to send the request

• If message is being sent to an external server, consider

encryption (Secure Socket Layer)
Allocation view

• Shows where the modules / components execute

• Useful to analyse performance, security, availability, etc.
Deployment view: Example
Client Client
Browser Browser

Firewall

Load Balancer
Server cluster / farm

Web server / App Server Web server / App Server Web server / App Server
SMS
gateway
Case Other Case Other Case Other (Telco)
module modules module modules module modules

Firewall

Primary Backup
DB DB
server server
Quality views
Apart from structural views, we can have other views to explain the architecture
to achieve specific quality attributes

• Security view: Shows different types of security measures such as

encryption, protocols, certificate servers, VPN, firewalls

• Communication view: Shows different communication channels and

mechanisms such as private and public networks, wireless and satellite
communication, communication protocols such as TCP/IP sockets, HTTP,
XML, JSON, communication mechanisms such as message queues, file
transfers, publish-subscribe

• Reliability view: Shows mechanisms used to implement reliability such as

replication, switch over, timing aspects.
Combining views: Example
Client
Business manager: Browser
How does the HTTP / SSL (encrypts user id & password)
system ensure that Firewall
login activity is
secure? Load Balancer

Web server / App Server

Login Data access

module modules

Firewall

Primary Backup Passwords are

DB DB encrypted and
server server stored
Combining views: Pre-paid
Account recharge
Modules and their interaction
Module view and C&C ATM
view - combined

Bank server
Modules and their interaction
Module view and C&C Example of a DB Client
view - combined accessing Database
server
Documentation
package
Documentation package: Example

Section 1: Primary presentation

Client Client

Firewall

Case Proceedings Evidences

mod. module module
Business
services

Scheduling Judgement
module module
Technical
services

Data access Workflow SMS gateway

SMS client
module engine (Telco)

Firewall

Mirroring
Documentation package: Example

Section 2: Element catalog

1. Name: Proceedings
Responsibilities:
• Maintain information about proceedings of different cases
• Allows entry by court staff and verification by judge
• Can retrieve linked evidences and documents
• Logs changes
Interface
• Add proceedings (Case code, Date, Text)
• Verify proceedings (Case code, Date)
• Retrieve evidences (Case code) Returns List of evidences

2. Name: SMS Client

Responsibilities:
• …
Interface
• ---
Documentation package: Example

4. Variability guide
• To switch to a different telecom service provider, switch the adaptor
(SMS client module) using configuration file
• To switch from Oracle to My SQL in the future, use features common
to all R-DBMS

5. Rationale
• Disk mirroring: This is to provide high availability when a disk fails
• Load balancer: This is to provide satisfactory performance when
number of users is large
• 2nd firewall: This is to protect the data from hackers
Appendix
Sample Architecture diagram of Web Portal system
showing different software layers & components
Presentation Services
Application Services

Clients Resource Managers

Directory & Security
Services
(SiteMinder)

Content Content
Management Management Corporate
Client (WCM) LDAP
Content
Managed Repository
Content
Legacy
Browser Applications
Web Portal
Reverse Web Server Services
Load
Proxy Content
Balancer Application
(Caching) Delivery
Logic

Static
Third Party Content
Systems or
Services Gateway Application
Internet Database
AKAMAI Services
Networks Services
Enterprise
Database(s)
Application and
Data Directories

Enterpise Security Management

Enterprise System Managment

Universal Layer
Sample Context diagram of a
Portal system
Context diagram shows the relationship of the system with rest of the systems in
the environment / eco-system
Allocation view: Example

Browser on client machines

Web server / App server on

each server

Business service modules and

Technical services modules
running on multiple servers
to address the load

DBMS software and data on a

separate server for data
protection
 Combining views: Example
Business manager: How does the system ensure that login activity is secure?

HTTPS & SSL used to encrypt

the messages flowing from
C&C view client to server
and
Allocation
view are
combined

Passwords are stored in a

separate server which is not
accessible from internet

Passwords are stored in encrypted

form. Anyone hacking into the
database will not be able to decrypt it
Example: High level architecture
of a Ticket booking application