explain your architecture using arc42

How do you explain your software architecture to fellow developers, management or other stakeholders?
arc42 promises „painless documentation“ - and in this talk Dr. Gernot Starke will show you how that works in practice:

Together we’ll have a look at effective usage of the arc42 documentation and communication template.
We cover several parts by explaining examples, and discuss how to introduce arc42 into your project.

Since more than a decade, the open-source arc42 software architecture documentation template
supports small, medium and large-scale systems around the globe. It has been created by practitioners,
with pragmatism and efficiency in mind. Details on https://arc42.org.

Transcript

1. Gernot Starke Fellow The Smart Way to Describe Your Architecture Photo by AndRo Poplis on Unsplash
2. Thanx to Michael Simons Twitter @rotnroll666
3. Photo by Jonada Molla on Unsplash
4. Missing in the picture
5. Technology (internal) Structure Interfaces Reasons Requirements
6. Architecture is (much) more than a diagram ...
7. and more than code …
8. http://www.flickr.com/photos/mistressf/737350025/sizes/l/
11. Template Repository for (architecturally) relevant information § Free and open source: arc42.org § Documentation https://docs.arc42.org
12. Results of Architecture Work... Requirements Decisions Code Structure & Components
13. 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
15. Sample (Data Migration, 4000+ PT)
16. Sample (CRM-System, 2000+ PT)
17. Sample „htmlSanityCheck“ https://github.com/aim42/htmlsanitycheck
18. HTML Sanity Checker Case Study for arc42 Architecture Documentation https://github.com/aim42/htmlSanityCheck (containing miserable source code by Gernot Starke)
19. 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
20. 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 >
21. Overview
22. Goal (Output) HTML report • Summary • Results by page • Minimally styled
23. Requirements (1): Checks
24. 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)
25. 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
26. (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
27. (Technical) Context
28. 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
29. 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
30. Building Blocks (HSC Core, Level 2)
31. HSC Core, Level 2 (ff)
32. Building Blocks (Checker, Level 3)
33. Building Blocks (ResultsCollector, L.3)
34. 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
35. 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
36. 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
37. 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
38. 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
39. 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
40. Start here: https://arc42.org/overview/
41. Continue here: https://docs.arc42.org
42. Tipps and FAQ (2)
43. Tooling? Whatever is available… Microsoft-Word… Wiki AsciiDoc in your IDE
45. Further info: leanpub.com/arc42byexample/c/JUG-Tirana Free for some days
46. Thanx! Questions? Dr. Gernot Starke gernot.starke@innoq.com 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