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. Gernot Starke
    Fellow
    The Smart Way
    to Describe Your
    Architecture
    Photo by AndRo Poplis on Unsplash

    View full-size slide

  2. Thanx to
    Michael Simons
    Twitter @rotnroll666

    View full-size slide

  3. Photo by Jonada Molla on Unsplash

    View full-size slide

  4. Missing in
    the
    picture

    View full-size slide

  5. Technology
    (internal) Structure
    Interfaces
    Reasons
    Requirements

    View full-size slide

  6. Architecture is
    (much) more
    than a
    diagram ...

    View full-size slide

  7. and more
    than code …

    View full-size slide

  8. http://www.flickr.com/photos/mistressf/737350025/sizes/l/

    View full-size slide

  9. Template
    Repository for (architecturally) relevant
    information
    § Free and open source: arc42.org
    § Documentation https://docs.arc42.org

    View full-size slide

  10. Results of Architecture Work...
    Requirements
    Decisions
    Code Structure
    & Components

    View full-size slide

  11. 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

    View full-size slide

  12. Sample (Data Migration, 4000+ PT)

    View full-size slide

  13. Sample (CRM-System, 2000+ PT)

    View full-size slide

  14. Sample „htmlSanityCheck“
    https://github.com/aim42/htmlsanitycheck

    View full-size slide

  15. HTML Sanity Checker
    Case Study for arc42
    Architecture Documentation
    https://github.com/aim42/htmlSanityCheck
    (containing miserable source code by Gernot Starke)

    View full-size slide

  16. 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

    View full-size slide

  17. 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
    >

    View full-size slide

  18. Goal (Output)
    HTML report
    • Summary
    • Results by page
    • Minimally styled

    View full-size slide

  19. Requirements (1): Checks

    View full-size slide

  20. 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)

    View full-size slide

  21. 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

    View full-size slide

  22. (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

    View full-size slide

  23. (Technical) Context

    View full-size slide

  24. 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

    View full-size slide

  25. 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

    View full-size slide

  26. Building Blocks (HSC Core,
    Level 2)

    View full-size slide

  27. HSC Core, Level 2 (ff)

    View full-size slide

  28. Building Blocks (Checker,
    Level 3)

    View full-size slide

  29. Building Blocks (ResultsCollector, L.3)

    View full-size slide

  30. 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

    View full-size slide

  31. 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

    View full-size slide

  32. 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

    View full-size slide

  33. 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

    View full-size slide

  34. 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

    View full-size slide

  35. 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

    View full-size slide

  36. Start here: https://arc42.org/overview/

    View full-size slide

  37. Continue here: https://docs.arc42.org

    View full-size slide

  38. Tipps and FAQ (2)

    View full-size slide

  39. Tooling? Whatever is available…
    Microsoft-Word…
    Wiki
    AsciiDoc in your IDE

    View full-size slide

  40. Further info:
    leanpub.com/arc42byexample/c/JUG-Tirana
    Free for
    some
    days

    View full-size slide

  41. 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

    View full-size slide