All solutions implicitly have an architecture, ideally one which is both intentional and documented. The Architectural Decision Records (ADR) process distributes architectural decision-making across team members. Accelerate the time-consuming process of hand drawing diagrams by rendering from a text-based source. Communicate effectively by committing both your markdown-based ADRs and text-based diagrams into your source code repository. This talk will review these techniques, provide actionable steps to adoption, and even live-code some examples.

1. Sharpen your "Architecture
Documentation" Saw
Architectural Decision Records (ADRs) and Diagrams-as-Code
Kevin Hakanson (he/him)
Sr. Solutions Architect, AWS
(opinions are my own)

2. When you start…
…looking at using new
software, libraries, SDKs, etc.
Do you read documentation
first or jump into reading the
source code?
…building new software
Parallel question – write
documentation first, or jump
into writing code?
2

3. Today’s Goals
• Learn about two Architecture Documentation techniques
• Architectural Decision Records (ADRs)
• Diagrams as Code
• Leave ready (and excited) to apply this knowledge
3

4. “
”
All solutions implicitly have an
architecture, ideally one which is
both intentional and documented.
Kevin Hakanson, “Classically Trained” Software Architect
4

5. Would you like architects with your architecture?
“Teams should keep Architecture Decision Records. Autonomy
shouldn’t translate into intransparency.” - Gregor Hohpe
5
Source: https://architectelevator.com/architecture/organizing-architecture/

6. Architectural Decision Records
(ADRs)
6

7. Documenting Architecture Decisions
Michael Nygard - November 15, 2011
• Track the motivation behind "architecturally significant" decisions:
• Those that affect the structure, non-functional characteristics, dependencies,
interfaces, or construction techniques.
• Keep in the project repository and use a lightweight text formatting
language like Markdown.
7
Source: https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions

8. 8
Source: https://martinfowler.com/articles/scaling-architecture-conversationally.html#adr

9. Example
Cloudscape Design System React
TypeScript Vite template
Personal “starter template” for building web
application demos using
https://cloudscape.design/
ADRs in source code repository under docs/adr
9

10. 10

11. AWS Prescriptive Guidance
Using architectural decision records to streamline technical decision-
making for a software development project
This guide introduces the architectural decision records (ADR) process for
software engineering projects. ADRs support team alignment, document
strategic directions for a project or product, and reduce recurring and time-
consuming decision-making efforts.
Darius Kunce and Dominik Goby, Application Architects
AWS Professional Services - March 2022
11
Source: https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html

12. Software Architecture and Design InfoQ
Trends Report - April 2023
“Architecture Decision Records (ADRs) are now commonly recognized
as a way to document and communicate design decisions.”
“Architects are always looking for improvements on how to document,
communicate, and understand decisions. This may be another area
where large language models will play a role in the future, acting as
forensic archeologists to comb through ADRs and git history.”
12
Source: https://www.infoq.com/articles/architecture-trends-2023/

13. ChatADR?
13

14. Diagrams-as-Code
14

15. Thoughtworks Technology Radar Blip
Published : Oct 28, 2020
“There are benefits to using [diagrams as code] tools over the heavier
alternatives, including easy version control and the ability to generate
the DSLs from many sources.
Tools in this space that we like include Diagrams, Structurizr DSL,
AsciiDoctor Diagram and stables such as WebSequenceDiagrams,
PlantUML and the venerable Graphviz.
It's also fairly simple to generate your own SVG these days, so don't
rule out quickly writing your own tool either. ”
15
Source: https://www.thoughtworks.com/en-us/radar/techniques/diagrams-as-code

16. Kroki (https://kroki.io/)
Creates diagrams from textual descriptions!
Kroki provides a unified API with support for BlockDiag (BlockDiag,
SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag), BPMN, Bytefield, C4
(with PlantUML), D2, DBML, Ditaa, Erd, Excalidraw, GraphViz, Mermaid,
Nomnoml, Pikchr, PlantUML, Structurizr, SvgBob, UMLet, Vega, Vega-
Lite, WaveDrom, WireViz... and more to come!
16

17. “
”
It depends…
Every architect (at some point)
17
Which tool should you pick?

18. 18
@startuml Use Cases
title Use Cases
left to right direction
actor "Kevin" as kevin <<architect>>
actor "Audience" as osn2023
rectangle "Diagrams" {
usecase "create presentation" as uc1
usecase "write documentation" as uc2
usecase "solution design" as uc3
usecase "?" as uc4
}
kevin --> uc1
kevin --> uc2
kevin --> uc3
osn2023 --> uc4
@enduml

19. Kevin’s ADRs for making diagrams
ADR001 - Use PowerPoint for presentations
High quality using official AWS Architecture Icons and easiest to edit when
combining slides from existing presentations.
ADR002 - Use DrawIO (desktop) for documentation
Exported images are included in project documentation, often created in
markdown format.
ADR003 - Use PlantUML for sequence diagrams
Sequence diagrams help improve understanding of design across success and
error use cases.
19

20. PlantUML
• Used to draw UML diagrams, using a simple and human readable text
description.
• Does not prevent you from drawing inconsistent diagrams.
• More of a drawing tool than a modeling tool.
• Open-source. Can download distribution and run locally.
java -jar scripts/plantuml-mit-1.2023.6.jar –picoweb
20
Source: https://plantuml.com

21. AWS Icons for PlantUML
PlantUML images, sprites, macros, and other includes for Amazon Web
Services (AWS) services and resources. Used to create PlantUML
diagrams with AWS components.
All elements are generated from the official AWS Architecture
Icons and when combined with PlantUML, are a great way to
communicate your design, deployment, and topology as code.
21
Source: https://github.com/awslabs/aws-icons-for-plantuml

22. Amazon S3 bucket-per-tenant model
22
!procedure $AWSIcon($service, $line1)
rectangle "$AWSImg($service)n$line1"
!endprocedure
$AWSIcon(Users, "Tenant 1") as tenant1
$AWSIcon(Users, "Tenant 2") as tenant2
AWSCloudGroup(cloud){
$AWSIcon(SimpleStorageServiceBucket, "tenant-1-bucket") as bucket1
tenant1 -r-> bucket1
$AWSIcon(SimpleStorageServiceBucket, "tenant-2-bucket") as bucket2
bucket1 -[hidden]r- bucket2
tenant2 -l-> bucket2
}

23. Architecture Diagrams
• Many architecture diagrams are a free-form mixture between a
structure diagram and a behavior diagram.
• structure: network connections between services
• behavior: numbered message arrows
• Sequence Diagrams are part a subset of behavior diagrams known as
interaction diagrams which emphasis control and data flow.
23

24. 24

25. 25

26. 26
user -> s3++ AWS_COLOR_GREEN: <$Callout_1> upload video
$UploadIcon(Multimedia, video)
user <-- s3:
s3 ->> e1++ AWS_COLOR_ORANGE: <$Callout_2> event
e1 ->> sfw--: start workflow
activate sfw AWS_COLOR_PINK
== audio ==
sfw -> sfw1++ AWS_COLOR_ORANGE:
sfw1 ->> mediaconvert: create job
activate mediaconvert AWS_COLOR_ORANGE
sfw <-- sfw1--:
mediaconvert -> s3: <$Callout_3> save audio
$UploadIcon(Tapestorage, audio)
sfw <<- mediaconvert--: task success
== transcript ==
sfw -> sfw2++ AWS_COLOR_ORANGE:
sfw2 ->> transcribe: start transcription job
activate transcribe AWS_COLOR_TURQUOISE
sfw <-- sfw2--:
transcribe -> s3: <$Callout_4> save transcript
$UploadIcon(Documents, transcript)
deactivate s3
sfw <<- transcribe--: task success
deactivate sfw

27. VS.
27

28. 28
@startuml Amazon S3 objects using IAM Temporary Credentials
title Amazon S3 objects using IAM Temporary Credentials
participant "User" as user
participant "Cognito User Pool" as userpool
participant "Cognito Identity Pool" as idpool
participant "S3 Bucket" as s3
participant "STS" as sts
participant "IAM Policy" as permissions
' 1. Authenticate and get tokens
user -> userpool: InitiateAuth
user <-- userpool: ID Token and Access Token
' 2. Exchange tokens for AWS credentials
user -> idpool: GetCredentialsForIdentity
idpool -> idpool: map to IAM Role
idpool -> sts: AssumeRoleWithWebIdentity(Role)
idpool <-- sts: temporary security credentials
user <-- idpool: temporary security credentials
' 3. Access AWS services with credentials
user -> s3: GetObject
s3 -> permissions: check permissions
alt no access
s3 <-- permissions: Deny
user <-- s3: error (AccessDenied)
else access
s3 <-- permissions: Allow
user <-- s3: S3 object
end
@enduml
Source: https://github.com/awslabs/aws-icons-for-plantuml/tree/main/examples/cognito-scenario

29. 29

30. 30

31. 31

32. Mermaid
JavaScript based diagramming and charting tool that renders
Markdown-inspired text definitions to create and modify diagrams
dynamically.
Four ways of using mermaid:
1. Using the Mermaid Live Editor at mermaid.live.
2. Using mermaid plugins with programs you are familiar with.
3. Calling the Mermaid JavaScript API.
4. Deploying Mermaid as a dependency.
32
Source: https://mermaid.js.org/

33. 33
Source: https://kevinhakanson.com/2022-10-02-sequence-diagrams-with-mermaid-and-diagramsnet/

34. C4 model for visualizing software architecture
1. System context diagram
2. Container diagram
3. Component diagram
4. Code diagram
• abstraction-first approach to
diagramming software
architecture
• notation independent that
works with variety of diagraming
tools
34
Source: https://c4model.com/

35. C4-PlantUML
35

36. 36
Person(user, "User", $tags="User")
System_Boundary(softwareSystem, "Video Transcription Service") {
Container(s3bucket, "Amazon S3 bucket", $tags="SimpleStorageServiceBucket")
Container(objectcreated, "ObjectCreated event handler", $tags="LambdaLambdaFunction")
Container(stepfunction, "transcribe workflow", $tags="StepFunctions")
Container(extractaudio, "extract audio", $tags="LambdaLambdaFunction")
Container(transcribeaudio, "transcribe audio", $tags="LambdaLambdaFunction")
Container(mediaconvert, "AWS Elemental MediaConvert", $tags="ElementalMediaConvert")
Container(transcribe, "Amazon Transcribe", $tags="Transcribe")
Rel(s3bucket, objectcreated, "ObjectCreated event")
Rel(objectcreated, stepfunction, "start")
Rel(stepfunction, extractaudio, "step 1")
Rel(extractaudio, mediaconvert, "start job")
Rel(mediaconvert, s3bucket, "save audio")
Rel(stepfunction, transcribeaudio, "step 2")
Rel(transcribeaudio, transcribe, "start transcription job")
Rel(transcribe, s3bucket, "save transcription")
}
Rel(user, s3bucket, "Uploads")

37. Structurizr
Structurizr builds upon "diagrams as code", allowing you to create
multiple software architecture diagrams from a single model.
There are a number of tools for creating Structurizr compatible
workspaces, with the Structurizr DSL being the recommended option
for most teams.
Specifically designed to support the C4 model for visualizing software
architecture.
37
Source: https://structurizr.com/

38. 38
workspace {
!adrs adrs
model {
user = person "User" {
tags "User"
}
softwareSystem = softwareSystem "Video Transcription Service" {
s3bucket = container "Amazon S3 bucket" {
tags "SimpleStorageServiceBucket"
user -> this "Uploads"
}
objectcreated = container "ObjectCreated event handler" "" "AWS Lambda function" {
tags "LambdaLambdaFunction"
component "Boto3" "AWS SDK for Python" {
technology "Python package"
url https://aws.amazon.com/sdk-for-python/
}
s3bucket -> this "ObjectCreated event"
}

39. Structurizr Lite (standalone, free version)
39
Source: https://structurizr.com/help/lite

40. ADR Tools
• A command-line tool for working with a log of Architecture Decision
Records (ADRs).
• Structurizr allows you to supplement your software architecture
model with a decision log, captured as a collection of lightweight
ADRs.
• Either created manually, or imported from tools like adr-tools.
40
Source: https://github.com/npryce/adr-tools

41. Call to Action
• Read Documenting Architecture Decisions from Michael Nygard (2011) and the
AWS Prescriptive Guidance from AWS Professional Services (2022)
• Review the different ADR templates and examples
• Use Diagrams-as-Code to draw render your next architecture diagram, either
with PlantUML or another tool
• Sequence Diagrams enrich your understanding of distributed architectures | AWS
Architecture Blog (amazon.com)
• Consider how your projects can benefit from these architecture documentation
recommendations
41

42. Thank You
Kevin Hakanson (kevinhakanson.com)
42