Upgrade to Pro — share decks privately, control downloads, hide ads and more …

explain your architecture using arc42

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.

Dr. Gernot Starke

December 15, 2020
Tweet

More Decks by Dr. Gernot Starke

Other Decks in Programming

Transcript

  1. Template Repository for (architecturally) relevant information § Free and open

    source: arc42.org § Documentation https://docs.arc42.org
  2. 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
  3. 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
  4. 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 >
  5. 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)
  6. 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
  7. (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
  8. 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
  9. 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
  10. 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
  11. 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
  12. 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
  13. 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
  14. 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
  15. 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
  16. 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