Slide 1
Slide 1 text
Gernot Starke
Fellow
The Smart Way
to Describe Your
Architecture
Photo by AndRo Poplis on Unsplash
Slide 2
Slide 2 text
Thanx to
Michael Simons
Twitter @rotnroll666
Slide 3
Slide 3 text
Photo by Jonada Molla on Unsplash
Slide 4
Slide 4 text
Missing in
the
picture
Slide 5
Slide 5 text
Technology
(internal) Structure
Interfaces
Reasons
Requirements
Slide 6
Slide 6 text
Architecture is
(much) more
than a
diagram ...
Slide 7
Slide 7 text
and more
than code …
Slide 8
Slide 8 text
http://www.flickr.com/photos/mistressf/737350025/sizes/l/
Slide 9
Slide 9 text
No content
Slide 10
Slide 10 text
No content
Slide 11
Slide 11 text
Template
Repository for (architecturally) relevant
information
§ Free and open source: arc42.org
§ Documentation https://docs.arc42.org
Slide 12
Slide 12 text
Results of Architecture Work...
Requirements
Decisions
Code Structure
& Components
Slide 13
Slide 13 text
arc42, Version 7.0, March 2017.
© Dr. Peter Hruschka und Dr. Gernot Starke.
Free for commercial and private use.
1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
Sample (Data Migration, 4000+ PT)
Slide 16
Slide 16 text
Sample (CRM-System, 2000+ PT)
Slide 17
Slide 17 text
Sample „htmlSanityCheck“
https://github.com/aim42/htmlsanitycheck
Slide 18
Slide 18 text
HTML Sanity Checker
Case Study for arc42
Architecture Documentation
https://github.com/aim42/htmlSanityCheck
(containing miserable source code by Gernot Starke)
Slide 19
Slide 19 text
Prerequisites
Required:
• Basic knowledge of HTML (link,
anchor, id, URI, ImageMap)
• Basic knowledge of Groovy +
Gradle
Disclaimer:
• System is seriously
over-documented
• Code is unfinished L
Slide 20
Slide 20 text
Intro and (Business) Goal
shall support authors
creating digital formats
with hyperlinks and
integration of images and
similar resources.“
1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
>
Slide 21
Slide 21 text
Overview
Slide 22
Slide 22 text
Goal (Output)
HTML report
• Summary
• Results by page
• Minimally styled
Slide 23
Slide 23 text
Requirements (1): Checks
Slide 24
Slide 24 text
Architecture Quality Requirements
Priority Quality Goal Scenario
1 Correctness Every broken internal link (cross reference) is found
1 Correctness Every missing local image is found.
1 Safety Content of the files to be checked is never altered.
2 Correctness Correctness of every checker is automatically tested
for positive AND negative cases
3 Correctness Every reporting format is tested: Reports must
exactly reflect checking results.
3 Performance Check of 100kB html file performed under 10 secs
(excluding gradle startup)
Slide 25
Slide 25 text
Constraints
Implemented on Java platform
•Preferably in Groovy
Runnable as Gradle-plugin without installation*
* except: Java runtime
Available under liberal Open-Source license
1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 26
Slide 26 text
(Business) Context 1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 27
Slide 27 text
(Technical) Context
Slide 28
Slide 28 text
Solution Strategy
• Use HTML parser with minimal dependencies
• Implement in Groovy
• Wrapping as Gradle-plugin becomes simple
• Apply Template-Method pattern for
•Checking algorithms
•Report generators
• (Details see chap 8: Crosscutting Concepts)
1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 29
Slide 29 text
Building Blocks (Level 1) 1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 30
Slide 30 text
Building Blocks (HSC Core,
Level 2)
Slide 31
Slide 31 text
HSC Core, Level 2 (ff)
Slide 32
Slide 32 text
Building Blocks (Checker,
Level 3)
Slide 33
Slide 33 text
Building Blocks (ResultsCollector, L.3)
Slide 34
Slide 34 text
Building Blocks
Hierarchy
Kontext
Level 1
Level 2
Level 3
H t ml S a n it y Check
use r
Bu ild sy st em (e.g .
G r adle, m ake)
loc al ht ml
file(s)
loc al i m ages
exter n al
websites &
resources
* Risk *
references
« p ost po n ed »
checks
checks
checks
references
H t ml S a n it y Check
loc al - ht ml loc al -i m ages
user
build - syste m
exter n al
websites
local - resources
HS C Co re
AllChecksRun ner
local file syste m
Results
ht t p
(exter n al)
HS C G r a d le
Plu gin
HSC Com m a n d
Lin e In t erfa ce
HS C G r a phic al
In t erfac e
done
pla n n ed
L
egend
via shell
HS C Co re
AllChecksRun ner
local file syste m
Results
ht t p
(exter n al)
«li br a r y »
H t ml P a rser
Results Collect o r
Fin d in g s
A ll Checks R un n e r
done
pla n n ed
L
egend
Ch ecker
Su ggest er
Re po r t e r
fin d
suggestions
crea te / execu te
1..
a d d Fin d in g
pa rse
Results
Results Collect o r
Results
Re po r t e r
Pe r - Ru n Results
Sin gle C heck Resu lts
w h a tIsC heck ed : St rin g
sourceIte m :St ring
t a r getIt em :St ri n g
n r OfIte msChecked :in t
Sin gle P age Resu lts
pageN a m e :St ring
pa geTit le :S t rin g
m et aInfo :PageMet aInfo
Fin d in g
it e m :S t rin g
sug gest ion :St rin g
Fin d in g s
a d d - Fin d in g
1.. *
0.. *
1
unused
i m ages
1
Classes:
AllChecksRunner
MissingConfigException
Packages:
o.a.h.check
o.a.h.collect
o.a.h.html
o.a.h.report
Classes:
Checker.groovy
ImageMapChecker
MissingImageFilesChecker
Slide 35
Slide 35 text
Runtime (perform all checks)
1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 36
Slide 36 text
Deployment
1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 37
Slide 37 text
Crosscutting Concepts 1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 38
Slide 38 text
Crosscutting Concepts
(Template Method)
Checking HTML (abstract)
public SingleCheckResults( HtmlPage pageToCheck ){
assert( pageToCheck != null)
checkingResults = new SingleCheckResults()
initCheckingResultsDescription()
return check()
} The Template Method defines a skeleton of an
algorithm in an operation, and defers some steps to
subclasses.
1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 39
Slide 39 text
Decisions
Result: Jsoup as HTML parser (http://jsoup.org)
Criteria A1:
Jsoup
A2:
HTMLUnit
No (!) external
dependencies
No deps >15 deps
Simple API simple simple
DOM-like navigation yes partially
Fast (1 MB page /
sec)
yes no
1. Introduction and Goals
1.1 Requirements Overview
1.2 Quality Goals
1.3 Stakeholders
7.Deployment View
7.1 Infrastructure Level 1
7.2 Infrastructure Level 2
….
2. Constrainst
2.1 Technical Constraints
2.2 Organisational Constraints
2.3 Conventions
3. Context and Scope
3.1 Business Context
3.2 Technical Context
4. Solution Strategy
5. Building Block View
5.1 Level 1
5.2 Level 2
….
6. Runtime View
6.1 Runtime Scenario 1
6.2 Runtime Scenario 2
….
8. Crosscutting Concepts
8.1 Domain Structures and Models
8.2 Architectural/Design Patterns
8.3 Under the hood
8.4 User Experience
….
9. Architectural Decisions
9.1 Decision 1
9.2 Decision 2
….
10. Quality Requirements
10.1 Quality Tree
10.2 Quality Scenarios
11. Risks and technical debts
12. Glossary
Slide 40
Slide 40 text
Start here: https://arc42.org/overview/
Slide 41
Slide 41 text
Continue here: https://docs.arc42.org
Slide 42
Slide 42 text
Tipps and FAQ (2)
Slide 43
Slide 43 text
Tooling? Whatever is available…
Microsoft-Word…
Wiki
AsciiDoc in your IDE
Slide 44
Slide 44 text
No content
Slide 45
Slide 45 text
Further info:
leanpub.com/arc42byexample/c/JUG-Tirana
Free for
some
days
Slide 46
Slide 46 text
Thanx!
Questions?
Dr. Gernot Starke
[email protected]
Krischerstr. 100
40789 Monheim am Rhein
Germany
+49 2173 3366-0
Ohlauer Str. 43
10999 Berlin
Germany
+49 2173 3366-0
Ludwigstr. 180E
63067 Offenbach
Germany
+49 2173 3366-0
Kreuzstr. 16
80331 München
Germany
+49 2173 3366-0
Hermannstrasse 13
20095 Hamburg
Germany
+49 2173 3366-0
Gewerbestr. 11
CH-6330 Cham
Switzerland
+41 41 743 0116
www.innoq.com