Making architecture decisions,
the Agile way

Lessons learned from my career

One of my first jobs as a junior developer

The Waterfall model

Consequences

• Big up-front investment
• Value provided to the company

Becoming a lead developer

Big ball of mud

The plan

My mistakes

• Introducing microservices
• Making decisions by myself
• Big Design Up Front (BDUF)

The Agile Manifesto

Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan

agilemanifesto.org

Does that mean we shouldn't take the time to think about architecture?

Principles behind the Agile Manifesto

agilemanifesto.org/principles.html

Continuous attention to technical excellence and good design enhances agility.

A good architecture makes it easy to respond to change

So how can you design your software while remaining Agile?

The best architectures, requirements, and designs emerge from self-organizing teams.

The teams that code the system
design the system

Working software is the primary measure of progress.

Simplicity--the art of maximizing the amount of work not done--is essential.

Make design decisions
"Just in Time"

Record architecture decisions

...but more importantly, record the reasons behind those decisions.

Architectural Decision

Architecturally Significant Requirement

Tabs vs. Spaces

Examples

• Programming language
• Framework
• Application architecture
• Communication protocols
• Database systems
• Testing strategy
• etc.

Architectural decision record (ADR)

Decision log

Michael Nygard's ADR format

• Title
• Context
• Decision
• Status
• Consequences

cognitect.com/blog/2011/11/15/documenting-architecture-decisions

Example

                            # 5. Storing data in a database

                            ## Context
                            Our application needs to store and retrieve data.
                            The data is structured and includes geospatial data.

                            ## Decision
                            We will use PostgreSQL as our database system as it
                            provides good support for geospatial data.

                            ## Status
                            Accepted

                            ## Consequences
                            The team needs to learn how to work with PostgreSQL.
                        

Markdown Any Decision Records (MADR)

• Title
• Context & Problem Statement
• Decision Drivers
• Considered Options
• Decision Outcome
  • Consequences
• Pros and Cons of the Options
• More Information

adr.github.io/madr

Example

                            # Storing data in a database

                            ## Context and Problem Statement
                            Our application needs to store and retrieve data.
                            The data is structured and includes geospatial data.

                            ## Considered Options
                            - MySQL
                            - PostgreSQL
                            - MongoDB

                            ## Decision Outcome
                            We will use PostgreSQL as our database system as it
                            provides better support for geospatial data than MySQL
                            and is more suitable for structured data than MongoDB.
                        

Benefits of ADR's

• Document decisions
• Record the reasons behind decisions
• Force you to consider multiple options
• Allow for re-evaluating decisions in the future
• Easy onboarding of new team members
• The outcome of one decision can be the context for another decision

Recommendations

Be objective

Keep ADR's brief

Decide on a template and stick to it

Number ADR's sequentially

Store ADR's in your project repo

Write ADR's in Markdown

Create diagrams using code

                            flowchart LR
                                FE[Frontend] --> Users
                                FE --> Billing
                                FE --> Orders
                                subgraph Microservices
                                    Users[Users microservice]
                                    Billing[Billing microservice]
                                    Orders[Orders microservice]
                                end
                                Users --> DB[(Database)]
                                Billing --> DB
                                Orders --> DB
                        

                                flowchart LR
                                    FE[Frontend] --> Users
                                    FE --> Billing
                                    FE --> Orders
                                    subgraph Microservices
                                        Users[Users microservice]
                                        Billing[Billing microservice]
                                        Orders[Orders microservice]
                                    end
                                    Users --> DB[(Database)]
                                    Billing --> DB
                                    Orders --> DB
                            

Main takeaways

• Attention to architecture improves agility
• Make design decisions "Just in Time"
• Involve the team in the decision-making process
• Use ADRs to document decisions and their rationale

More information

adr.github.io

ADR templates, best practices, tools for managing ADRs, etc.

Training courses

PHP, Symfony, OOP, Docker, Kubernetes, Terraform

nicwortel.nl/training

Use DPC24 for 10% off

Thank you!

Please give me feedback:

nicwortel.nl     @nicwortel