It sounds dull but good architecture documentation is essential. Especially when you are actively trying to improve your architecture.
For example, I spend a lot time helping clients modernize their software architecture. More often than I like, I’m presented with a vague and lifeless collection of boxes and lines. As a result, it’s sometimes difficult to discuss the architecture in a meaningful and productive way. In this presentation, I’ll describe techniques for creating minimal yet effective documentation for your application’s microservice architecture. In particular, you will learn how documenting scenarios can bring your architecture to life.
6. The goal of architecture is to
satisfy non-functional requirements
Nonfunctional
requirements
Development
Runtime
Scalability
Performance
Availability
…
Maintainability
Testability
Deployability
…
Often neglected
7. About software architecture
“The software architecture of a computing system is the
set of structures needed to reason about the system,
which comprise software elements, relations among
them, and properties of both.”
Documenting Software Architectures, Bass et al
8. De
fi
ningthe architecture of a new application
Learningthe architecture, e.g. new team member
Evaluatingthe architecture in order to improve it
Evolvingthe architecture to satisfy changed requirements
“The software architecture of a computing system is the
set of structures needed to reason about the system,
which comprise software elements, relations among
them, and properties of both.”
18. @crichardson
Different views describe different
aspects of the architecture
Logical
View
Process
View
Deployment
View
Implementation
View
Dev Ops
Modularity
Loose coupling
Availability
Scalability
19. +1 = 5th view = Scenarios
Logical
View
Process
View
Deployment
View
Implementation
View
Scenarios
Derived from use cases/stories
Animate the views
Elements from a
view
20. @crichardson
Views: more than just pretty
pictures
«Service»
Order Management «Service»
Consumer
Management
«Service»
Credit Card Payments
«Service»
Restaurant
Management
«Service»
Accounting
«Service»
Kitchen Management
«Service»
Service
«Database»
Database
Uses API
Legend
Part-of
«Service»
API Gateway
«async»
«subscribes to»
«async»
«async»
«async»
«async»
«sync»
«sync»
«sync»
«sync»
«sync»
Diagram Description of elements and relations
21. @crichardson
Alternatives to the classic 4+1
views
There are other views, e.g.
Modern deployment technologies (Kubernetes, Serverless)
don’t
fi
t with process/deployment views
Hybrid views and scenarios that mix elements (e.g. services
and entities)
Git repository/Service/Deployment pipeline view
…
Goal is communicate => use the views that are useful
39. @crichardson
Deployment: K8S cluster/AWS
3 AZ EKS cluster
Ingress managed ALB
3 AZ RDS Aurora
React application static resources
S3 bucket
api.app.acme.com app.acme.com
Browser
Cloudfront
<<service>> Order management
API Gateway
Managed Apache Kafka
React
SPA
40. @crichardson
Deployment view: description
ReactJS frontend served by Cloudfront from S3 bucket
Application services (+ API Gateway) deployed on AWS EKS:
K8S service + deployment
API entry point = K8S Ingress managed ALB
AWS resources (EKS, RDS Aurora, MKS, …) deployed to
three availability zones
45. @crichardson
Vision
FTGO is a food delivery application.
Consumers use FTGO to place food orders at
local restaurants.
FTGO coordinates a network of couriers who
deliver the orders. It’s also responsible for
paying couriers and restaurants.
Restaurants use the FTGO website to edit
their menus and manage orders.
47. Architecturally signi
fi
cant user
stories/scenarios
Capture the essence of the
application
In
fl
uence the architecture:
Complex, e.g. span multiple
subdomains
Business critical/highly
available
Low latency
Process large amounts of data
….
49. @crichardson
Business
objects
Distill scenarios into system
operations
FTGO
Application
createOrder()
fi
ndOrder()
…
Via UI
Application
Invokes
Subscribes to
Triggers
Model application behavior
cancelOrder()
≪commands≫
≪queries≫
…
Mutates and queries
Business
objects
54. @crichardson
Summary
The software architecture of a computing system is the set of
structures needed to reason about the system
Architecture is multi-dimensional
Each dimension is described by a view
View = elements + relations + their properties = pictures and words
Documenting architecturally signi
fi
cant user stories/scenarios is
essential
Scenarios animate the elements of a view and connect it to
functional requirements