iSAQB

Study Notes

Architecture documentation (C3)

Value of architecture documentation

overall structure

Architectural Views

Context View | level-0

"Context"

clarify 2 important aspects

External interfaces

comprise all parts of the environment that are relevant to the system

to distinguish between our system and "everything else" and relationship between our system and its environment

interfaces to neighboring systems

Type

Technical Context

Document the context view

UML component, package or class diagram or free form diagrams

Sample diagram: Context View Diagram

System scope

Building block / component View

Runtime View

Deployment View

explain the STATIC decomposition of system into building blocks (modules, components, subsystems...) & their relationship (interfaces, dependencies, associations...)

composition of software building blocks

DYNAMIC view, interaction between building blocks at runtime

hardware and tech infras...

Document the view

UML class, package, component diagrams

Document the view

UML sequence diagrams, activity diagrams, object diagrams...

Document the view

UML deployment diagrams

shows tech details (transmission channel, technical protocol...)

Quality requirements

  • Correctness
  • Understandability
  • Efficiency
  • Appropriateness
  • Maintainability - easy to change

to be current

helpful

easy to find

adequate

Completeness is NOT a goal or requirement for documentation

Architecture decisions

Architectural decision

Architecture Decision Record (ADR) is a template to document an architectural decision

Title: unique ADR identifier

Status: proposed, accepted, rejected...

Context: what is the issue that we are seeing that is motivating this decision

Decision: what is the change we are proposing

Consequences: what becomes easier or more difficult to do because of this change

Business Context (Logical Context)

diff between outside and inside of system

  • any decisions within software architecture that concern architecturally significant requirements
  • hard to take and/or hard to change
  • often affect fundamental structure, quality characteristics, external interfaces ...

choices of technologies, structures, pattern, implementation style...

Reasons for architectural decisions

Technology choices

cross-cutting concepts

Stakeholder-specific documentation
SA need to hep create documentation that fulfills the needs of different stakeholders

Format (wiki, single/multiple documents

Style (text, diagram...)

Structure (generic template, specific structure...)

Notation (e.g. UML)

Depth

template-based documentation
fixed structure, uniform structure

understandability is improved, the structure of documentation is optimized for readability

retrievability, who know the overall structure -> easily find the desired information

re-use appropriate parts of documentation in other systems

lower effort to maintain

depends on

specifics of system

requirements

risks

development

organization

written or verbal communication

the amount and level of detail of documentation needed at each stage of development

documentation format

accessibility of documentation

formality of documentation (diagrams, simple drawings...)

formal reviews and sign-offs for documenation

Architecture development

Approaches for architecture development

Top-down

Bottom-up

start from GENERAL, ABSTRACTION, BIRD'S EYE PERSPECTIVE and step into details

keep things CONSISTENT over various components

Reduce risks

Build PoC implementations

View-based architecture

VIEWs focus on specific concerns, parts or aspects of system

separation of concerns

address specific stakeholder concerns

Iterative and incremental design

Iterative

Incremental

repeated cycles (iterations) - delivers or improves part of system

after each iterations, feedback from stakeholders is collected => learning and improvement is based upon this feedback

each increment delivers a slice of functionality

Advantages

problems are detected early => more time to resolve

development and rollout activities are performed in every iteration => routine processes and less errors

changes in requirements / technologies can be taken into account

development risks and uncertainties are minimized

Domain-Driven Design

approach for developing software for complex application domains

facilitate common understanding of important business terminology between development team and business people by creating a common (UBIQUITOUS) language used by both groups

development team: UBIQUITOUS languages => code

2 approaches

Strategic design - top down approach
bounded contexts

tactical design - bottom up approach
identify events, services, entities and value object (data)

Evolutionary architecture

Design software architectures

Design and communicate software architectures

(1) take design decisions

(2) communicate these decisions

factors

requirements and constraints

available components, technologies and other elements

available skills in dev team

potential conflicts between goals, requirements and constraints

structural decisions

structural elements (building blocks)
e.g. source code artifacts, frameworks, files...
building block: general term for all kinds of artifacts from which software is constructed

dependencies (of structural elements)

black box

white box

we might use black box to delegate responsibility for the design and implementation of this building block to somebody else

hides

the interior structure (internal building blocks and internal dependencies)

internal processing, algorithm or functions

internal data and data structure

exposes

responsibility: what this black box does, its functions or service

provided interfaces: what functions, services, data this black box provide

required interfaces: what other functions, services, data this black box requires to fulfill its responsibility

additional info

additional attributes

  • this black box is capable of multi user access
  • what are guaranteed, minimal or average response time...

known restrictions, risks or problems

design rationale: explain the reason why it is structured in this specific way

decomposition by changing from black box to white box

  • to increase levels of details

facilitate understanding of low-level structures by showing these structures in context

can start designing and implementing system on any abstraction level and use a combination of bottom up and top down approaches during development

recognize interdependencies and trade-offs between design decisions

as many decisions will have consequences

stepwise refinement

is top-down approach for the design process

is approach to identify or design the building blocks of system

design architecture views

architecture views support both designing and communicating architectures => they are more than just a means of documentation

relation of building blocks to source code

ultimately building blocks will be implemented in source code

Separate technical aspects from domain-related elements

if domain-related elements of system are coupled to purely technical details (like file names, specific database names...) => more difficult to understand, change or test

identify risks related to architectural decisions

Trading off one attribute or quality against another might be a risk for some stakeholders => should consider and communicate such risks

Influencing factors and constraints to software architecture

Product-related factors

functional requirements

quality requirements & quality goals

additional factors: product costs, licensing model, business model of system

Technological factors

externally mandated technical decisions and concepts

existing or planned hardware and software infrastructure

technological constraints on data structure and interfaces

reference architectures, libraries, components and frameworks

programming languages

organization factors

organizational structure of dev team and of customer

company and team cultures

partnerships and cooperation agreements

standards, guidelines, process models (approval / release processes)

available resources (budget, time, staff)

availability, skillset, commitment of staff

regulatory factors

local and international legal constraints

contract and liability issues

data protection and privacy laws

compliance issues or obligations to provide burden of proof

Trends

market trends

technology trends

methodology trends (Agile)

impact of further stakeholder concerns and mandated design decisions

Cross-cutting concepts

affect several building blocks of system

to solve recurring problems (or cross-cutting concerns) - addressed within multiple elements of architecture

cross-cutting decisions can help to ensure CONSISTENCY - implement in same manner, same technology, use same patterns

Risks: if the standard is bad, systems using the standard will also be bad

Architectural Patterns

sample patterns

Layers

Pipes-and-filters

Microservices (aka self-contained-systems)

Dependency injection

architect know various architectural patterns and apply them when appropriate

patterns are a way to achieve certain qualities for given problems and requirements within their contexts

abstraction layers: lower layers hide certain details from the layers above

layers (tiers) to separate functionality or responsibility, e.g 3-tier architecture

characteristics

dependencies (function or method calls) go down from upper to lower layers

strict layering: communication from one layer is restricted to the layer immediately below ti

loose layering: one layer may access all layers below it

advantages/ disadvantages

advantages

disadvantages

unidirectional dependencies between layers avoid circular dependencies

simple structure, easy to understand

lower efficiency - requests from uppermost layer cross several layer boundaries until they reach the lower layers

cascade of changes when behavior of a single layer changes

Design Principles

Abstraction

Modularization (Building block principle)

  1. encapsulate responsibilities
  2. expose well defined interfaces only
  3. can be developed and maintained independently
  4. can be replaced by other modules with identical interfaces without side effects

Conceptual Integrity

Simplicity

Expect errors

Information hiding and encapsulation

SoC

Loose coupling

High Cohesion

SOLID

Single Responsibility Principle

Open/Closed principle

Liskov substitution principle

Interface segregation principle

Dependency inversion principle

vs SoC, SRP: a component should be responsible for a single concern. SoC is about dividing a system into components in a way that their concerns overlap as little as possible

open for extension, closed for modification

objects of a superclass shall be replaceable with objects of its subclasses without breaking the application

Clients should not be forced to depend upon interfaces that they do not use.


https://reflectoring.io/interface-segregation-principle/

Managing dependencies

Achieve Quality requirements

Design and define interfaces

interface categories

Provided interfaces or Application Programming Interfaces (API)-
what is needed to USE the provided functions

Service Provider Inteface (SPI) - intended to be IMPLEMENTED or EXTENDED by another component / system

Required Interfaces - describe what a component needs to fulfill its responsibilities

Important Notes

quantitative evaluation

qualitative analysis

quality conflicts:
Usability - Security
Runtime configurability Robustness

reasons for maintaining adequate architecture documentation: to conform to regulatory or legal constraints

ATAM Architecture Tradeoff Analysis Method

quality model

quality tree

quality scenarios

usage scenarios

change/modification scenarios

failure scenarios

Example: generate daily sales report in < 15 sec

Event: generate daily sale report

Response: generated report

Metric: generating in < 15 sec

ISO 25010

CPSA-F Preparation

Mock exam

Offline Mock Exam

Books

Effective Software Architectures

shows external relationships from non-tech perspective