Software Architecture
of Oviedo of University
Software Architecture
Documentation
Science Computer
of of Course 2018/2019 Jose E. Labra Gayo School Software Architecture
Contents of Oviedo of
Communicating software architecture University Goal of documentation Documentation stakeholders Views Documentation and agile projects Guidelines Documentation approaches Kuchten 4+1 views
Science Views and beyond
C4 model Computer
of of Arc42 School
Software Architecture
of Oviedo of
University
Science
Computer
of of School Software Architecture
of Oviedo of Architecture is more than code
University The code doesn't tell the whole story Questions the code doesn't answer How the software fits into existing system landscape? Why the technologies were chosen? What's the overall structure of the system? Where the components are deployed at runtime? How do the components communicate? How and where to add new functionality?
What common patterns and principles are used? Science How the interfaces with other systems work?
Computer How security/scalability/… has been achieved? of of
. . . School Software Architecture
of Oviedo of Goal of documentation
Main goal: communicate the structure University Understand the big picture Create a shared vision: team and stakeholders Common vocabulary Describe what the sofware is and how is being built Focus for technical conversations about new features Provide a map to navigate the source code Justify design decisions
Science Help new developers that join the team
Computer
of of School Software Architecture
Documentation requirements of Oviedo of
Understandable by different stakeholders University Technical and non-technical stakeholders Reflect the reality Be careful of the model-code gap Move fast and adapt to changes Adapt to agile projects
Evolutionary architecture
Science
Computer
of of School Software Architecture
Rules for good documentation of Oviedo of
University Write documentation from reader's point of view Find who will be the readers and their expectations Avoid unnecessary repetition (DRY principle) Avoid ambiguity Explain the notation (or use a standard one) For diagrams, use legends Use a standard organization or template Add TBD/To do when necessary Science Organize for easy of reference/links
Computer Record rationale of of
Keep documentation current School Software Architecture
Problem vs Solution space of Oviedo of
University Software architecture = path from problem to solution Understand the problem Design a solution Rationale for the solutions proposed Record different design alternatives
Problem Solution Space Space Stakeholders Building blocks
Science Context Interfaces Quality goals Components Constraints Patterns/styles
Computer Principles Tactics
of of … … School Software Architecture
Views & viewpoints of Oviedo of
University Software architecture is a complex entity It cannot be described in a single 1-dimension It requires several views for different stakeholders View = A representation of a system with regards to some concerns Different views support different goals and uses Viewpoint = A collection of patterns, templates and conventions for constructing a view
Science Examples: structure, behaviour, deployment
Computer
of of School Software Architecture Documenting views of Oviedo of Introduction
University Textual description of the view Diagram(s) Add descriptive title including structures depicted Create a legend to explain meaning of symbols Don't forget to explain the lines/arrows List of elements and responsibilities Give descriptive names Define your terms (include a glossary)
Science Rationale
Computer
of of School Software Architecture
Documenting views of Oviedo of
Strive for Consistency and simplicity University Keep elements consistent Colors, shapes, arrows,… If you use a color scheme, follow it consitstently Check names across views,… Record possible inconsistencies Avoid too many details Remember Miller's law
Average person can keep 7 ( 2) elements in memory
Science
Computer
of of School Software Architecture
Tools for diagrams of Oviedo of
Sketches University Drawing tools for diagrams Text-based diagramming tools Modeling tools Reverse-engineering the model
Architecture description languages
Science
Computer
of of School Software Architecture
Sketches of Oviedo of
University Most people start with a sketch on paper or whiteboard Great way to collaborate and exchange ideas Usually intended for short lifespan But sooner or later, they must be recorded Simple approach: Photos
And later conversion to diagrams or models
Science
Computer
of of School
Fuente: https://c4model.com/ Software Architecture
Drawing tools for Diagrams of Oviedo of
University Desktop Microsoft Visio, Omnigraffle, SimpleDiagrams, … Web-based: draw.io, gliffy, LucidChart,… Drawing tools of general-purpose tools:
Word, Powerpoint, Keynote,… Science Front User Backend
Computer End DB
of of School Software Architecture
Text-based diagramming tools of Oviedo of
University Usually based on UML WebSequenceDiagrams, yUML, nomnoml PlantUML: http://plantuml.com/
@startuml Agent -> Agent : init Agent -> Manager : sendEmail() Agent <-- Manager : reply X Agent -> Manager : blabla( X ) User -> Manager : check( X )
Science User <-- Manager : ok
@enduml
Computer of of
School PlantUML Online: https://www.planttext.com/ Software Architecture
Modeling tools of Oviedo of
Allow to create a model of the software system University Visual representations are generated from model Alternatives: Sparx Enterprise Architect, Visual Paradigm, Archi, StarUML, ArgoUML, Modelio,… Usually support different notations UML, SysML, BPMN, ArchiMate Useful for up-front design
Science Good for refactoring & renaming components…
Computer
of of School Software Architecture
Reverse-engineering the model of Oviedo of
University Some of the previous modelling tools support this Static analysis tools: Structure101, NDepend, Lattix, Sonargraph,… Create the model based on existing code Useful to visualize existing codebases Problem: Resulting diagrams tend to include too much details
Science Difficult to see the architecture
Computer
of of School Software Architecture Architecture Description Languages
of Oviedo of ADLs
University Formally define the architecture of a system Create textual descriptions instead of diagrams Formal specification Describes the structure and behaviour Mostly in academic environments Not very popular in industrial settings Some examples:
xArch/xADL (http://isr.uci.edu/projects/xarchuci/) Science
ACME (http://www.cs.cmu.edu/~able/) Computer
of of AADL (http://www.aadl.info/) School Software Architecture
Software architecture templates of Oviedo of
University Several possibilities Kruchten 4+1 views Views & beyond C4 model Arc42 templates
. . .
Science
Computer
of of School Software Architecture
Kruchten 4+1 views of Oviedo of Embraced as part of Rational Unified Process
University 5 concurrent views 1 Logical view: functionality of the system 2 Development view: modules, layers,... 3 Process view: execution units, concurrency,… 4 Physical view: Infrastructure & deployment topology (+1) Scenarios view: selected use cases or scenarios
End-user Programmers Functionality Software management Logical Development view view
Science Scenarios Process Deployment Computer System engineers
of of view view Integrators Topology Performance Communications
School Scalability Software Architecture
Views and beyond of Oviedo of
Select a set of viewpoints University According to stakeholder's needs Define views according to those viewpoints Add a "Beyond views" document Overall architecture Information about how views relate
. . .
Science
Computer
of of School Software Architecture
C4 model (https://c4model.com/) of Oviedo of
University Describe Context: System or enterprise context diagram Container diagram: high level shape Components diagram: zoom and decompose Code: UML class diagrams, ER diagrams, … Documentation guidebook Context Code Functional overview Data Infrastructure architecture Science Quality attributes Constraints Deployment
Principles Development environment Computer
of of Operation and support
Decision log School Software Architecture
Arc42 https://arc42.org/ of Oviedo of
Structure to document software systems University Goal: Clear, simple and effective Templates available for several systems Asciidoc Word (docx) Markdown LaTeX ReStructuredText
Science Confluence
. . .
Computer
of of School Software Architecture
Arc42 overview of Oviedo of
1.- Introduction and goals University Problem 2.- Constraints 3.- Context & scope 4.- Solution strategy 5.- Building block view 6.- Runtime view 7.- Deployment view Solution 8.- Crosscutting concepts 9.- Architectural decisions
Science 10.- Quality requirements
11.- Risks and technical debt Computer
of of 12.-Glossary School
Picture source: https://commons.wikimedia.org/wiki/File:Ficherosclasicoscatalogo.JPG Software Architecture
1 - Introduction and goals of Oviedo of
University Short description of: - Requirements - Main quality goals
- Stakeholders
Science
Computer
of of School
Picture source: https://arc42.org/overview/ Software Architecture 1 Introduction and goals
of Oviedo of 1.1 Requirements overview University Short description of functional requirements Use-case tables It can link to existing requirements documents Full requirement documents are usually longer
Select architecturally significant requirements
Science
Computer
of of School Software Architecture 1 Introduction and goals
of Oviedo of 1.2 Main quality goals
University Enumerate the main quality goals Quality goals: Main quality attributes that the system needs to achieve
Format: A simple table can suffice Science
Example: Computer
of of https://biking.michael-simons.eu/docs/index.html#_quality_goals School Software Architecture
How to choose quality attributes? of Oviedo of
Quality attribute workshops University Involve stakeholders to prioritize quality attributes It may be helpful to distinguish Runtime quality attributes Performance, security, availability, usability,… Non-runtime quality attributes Modifiability, portability, reusability,testability Business quality attributes
Cost, schedule, time-to-market, …
Science
Computer
of of School Software Architecture
How to choose quality attributes? of Oviedo of
ISO-25010 Software Quality Model University 2 parts: Product quality, Quality in-use
Product Quality
Functional Performance Compati- Relia- Maintaina- Porta- Usability Security suitability efficiency bility bility bility bility
In-use Science
Freedom Context Effectiveness Efficiency Satisfaction
Computer from risk coverage
of of School Software Architecture 1 Introduction and goals of Oviedo of 1.3 Stakeholders University Stakeholder: person who affects, is affected or can contribute to the system and its architecture Make explicit expectations and motivation Format: table or map
Stakeholder Description Expectations, motivations
......
Science
Computer
of of School Software Architecture
2 - Constraints of Oviedo of Anything that constrains teams in design and University implementation decisions Sometimes at organization level Decisions already taken Format: a table with explanations Can be divided in organizational, technical, etc.
Constraint Explanation
......
Science
Computer
of of School
Picture source: https://arc42.org/overview/ Software Architecture
3 - Context and scope of Oviedo of
Delimits the system from external partners University Neighbouring users and systems Specifies the external interfaces
Business and technical perspective
Science
Computer
of of School
Picture source: https://arc42.org/overview/ Software Architecture 3. Context and Scope of Oviedo of 3.1 Business context University Specify all partners involved in the environment Format: Diagram or table Diagrams that show the system as a black box
Optional: Explanation of external interfaces
Science
Computer
of of School Software Architecture 3 Context and scope
of Oviedo of 3.2 Technical context University Specify Technical interfaces that link the system with the environment Format: Diagram or table
Usually: UML deployment diagrams
Science
Computer
of of School Software Architecture
Business context vs technical context
of Oviedo of
University
Science
Computer
of of School Software Architecture
4 - Solution strategy
of Oviedo of University Summary of fundamental decisions and strategies Can include: - Technology - Top-level decomposition - Approaches to achieve top quality goals - Relevant organizational decisions. Format: short text description
Science Keep explanations of key decisions short
Computer
of of School
Picture source: https://commons.wikimedia.org/wiki/File:Light_Bulb_or_Idea_Flat_Icon_Vector.svg Software Architecture
5 - Bulding block view of Oviedo of
University Static decomposition of system Modules of the system Hierarchy of white boxes containing black boxes Format: Start with overall overview diagram Decompose into other diagrams
Usually: UML Component diagrams
Science
Computer
of of School
Source: https://arc42.org/overview/ Software Architecture
6 - Runtime view of Oviedo of
University Behavior of building blocks as scenarios Important use cases or features Interactions at critical external interfaces Error and exception behavior. Format: Many notations Natural language (list of steps) UML sequence diagrams Science Flowcharts
BPMN Computer
of of … School
Source: https://arc42.org/overview/ Software Architecture
7 - Deployment view of Oviedo of
University Technical infrastructure with environments, computers, processors, topologies. Mapping of (software) building blocks to infrastructure Format: Usually: UML deployment diagrams
Add mapping tables
Science
Computer
of of School
Source: https://arc42.org/overview/ Software Architecture
8 - Crosscutting concepts of Oviedo of
University Approaches relevant in multiple parts of system Topics like: Domain model Architecture pattern and styles
Specific rules
Science
Computer
of of School
Source: https://arc42.org/overview/ Software Architecture
9 Architectural decisions of Oviedo of
University Important, expensive, critical, large scale or risky architecture decisions Include rationale for the decisions Format: List or table ordered by importance
Architecture decision record for important decisions
Science
Computer
of of School
Source: https://arc42.org/overview/ Software Architecture
10 - Quality requirements of Oviedo of
University Quality requirements as scenarios Quality tree to provide high-level overview The most important quality goals should have been
described in section 1 (quality goals)
Science
Computer
of of School Software Architecture 10. Quality requirements
of Oviedo of 10.1 Quality tree
University A quality tree with quality scenarios as leafs Include priorities for an overview Sometimes, large number of quality requirements. Format: A mind map with quality categories as branches
Include links to scenarios of the following section
Science
Computer
of of School Software Architecture 10. Quality requirements
of Oviedo of 10.2 Quality scenarios
University Scenarios describe what should happen when a stimulus arrives at the system. 2 types: Usage: runtime reaction to a certain stimulus. "The system reacts to a user’s request within 1 sec." Change: modification of the system or its environment "A new user type must be added"
Format: Tabular or free form text.
Science
Computer
of of School
Source: https://arc42.org/overview/ Software Architecture
11 - Risks and technical debt of Oviedo of
University Known technical risks or technical debt What potential problems exist? What does the development team feel miserable about? Format: List or risks/technical debts Include suggested measures to minimize, mitigate or avoid
risks or reduce technical debts.
Science
Computer
of of School
Source: https://arc42.org/overview/ Software Architecture
12 - Glossary of Oviedo of
University Important domain and technical terms Terms used by stakeholders when discussing the system Common vocabulary Translation reference in multi-language environments Format: table
Term Definition
Science ......
Computer
of of School
Source: https://arc42.org/overview/