What I Learnt Teaching Agile Software Architecture

2021 09 02 head

I am teaching agile software architecture and techniques SWAT as advanced bachelor level lecture weighted with 3 ECTS.

I gave this training the last three years at Lucerne University of Applied Sciences and Arts HSLU in Switzerland.

All materials are released under the Creative Commons copyright.

The course contents are aligned with the big software architecture programs.

The Open Group organization is the steward of TOGAF standard. TOGAF is the worldwide industrial standard for enterprise software architecture.

The group has realized that software and enterprise architecture must incorporate the agile principles [1], [2].

All students had formal training in Java, object-oriented programming and design, and agile software project approaches.

The school is still teaching waterfall and hybrid methods as a main approach for digital product development. One consequence is that students have a shallow understanding of more modern frameworks such as Scrum or DevOps.

The official proficiencies for the Scrum roles Scrum Master[4], Product Owner[5], and Developer[6] are not achieved with the current curriculum.

SWAT Lecture Content

The lecture description is:

  • Teaches the basics of systematic agile design of an adequate software architecture for a selected application.

  • Methods of agile quality assurance and software craftsmanship are explored using predefined or self-selected projects of students.

The fourteen lecture themes are:

  1. Traditional and Agile Approaches for software product architecture

    1. Why Agile Architecture and Design?

    2. Evolution of Software Architecture over the last Decades

    3. What is Agile Architecture?

    4. Agile Approaches with Scrum, XP, LeSS

  2. Agile Components and Subsystem Design and Continuous Improvements

    1. Refactoring

    2. Errors, Vulnerabilities, Smells in Source Code

    3. Architecture of Components and Subsystems

    4. Verify Functional Features

    5. Validate Quality Attributes of a Software Architecture

  3. Agile Application Architecture and Domain Driven Design

    1. Architecture Documentation

    2. Architecture Trends I

    3. Architecture Trends II

    4. Domain Driven Design Workshop

    5. Team and Technical Excellence for Architects

The slides of the SWAT course are available for all interested parties.

The course provides mandatory and optional literature for studying.

The reference texts are [1, 2, 3, 4].

The following books are recommended for interested students [5, 6, 7, 8, 9]. Each book is quite compact and can read over a weekend.

The lecturer can also use [10, 11] for the workshop parts.

arc42 Architecture Approach

The course discusses the key points defined in approaches such as arc42. The same concepts can naturally be found in TOGAF with a slight different terminology. The main sections in the arc42 documentation:

Introduction and Goals

Short description of the requirements, driving forces, extract (or abstract) of requirements. Top three (max five) quality goals for the architecture which have the highest priority for the major stakeholders. A table of important stakeholders with their expectation regarding architecture.
Agile defines the product vision, goals, and roadmap. Stakeholder management has a strong emphasis and is the responsibility of the product owner.


Anything that constrains teams in design and implementation decisions or decision about related processes. It can sometimes go beyond individual systems and are valid for whole organizations and companies.
Define, track and verify through fitness functions.

Context and Scope

Delimit your system from its (external) communication partners (neighboring systems and users). Specify the external interfaces. Shown from a business/domain perspective (always) or a technical perspective (optional)
Define and document using the UML or C4 approach.

Solution Strategy

Summary of the fundamental decisions and solution strategies that shape the architecture. Can include technology, top-level decomposition, approaches to achieve top quality goals and relevant organizational decisions.
Document through an architecture document, architecture workshops and diagrams.

Building Block View

Static decomposition of the system, abstractions of source-code, shown as hierarchy of white boxes (containing black boxes), up to the appropriate level of detail. Document through an architecture document, architecture workshops and diagrams. Complex UML models are useless and not maintainable.

Runtime View

Behavior of building blocks as scenarios, covering important use cases or features, interactions at critical external interfaces, operation and administration plus error and exception behavior.+ Documented through automated tests and if necessary diagrams. Complex UML models are useless and not maintainable.

Deployment View

Technical infrastructure with environments, computers, processors, topologies. Mapping of (software) building blocks to infrastructure elements.
Infrastructure as code document the infrastructure and the solution deployment. Usually deployment diagrams are useless.

Cross Cutting Concepts

Overall, principal regulations and solution approaches relevant in multiple parts (→ cross-cutting) of the system. Concepts are often related to multiple building blocks. Include different topics like domain models, architecture patterns and styles, rules for using specific technology and implementation rules.
Should be documented as architecture decisions.

Architecture Decisions

Important, expensive, critical, large scale or risky architecture decisions including rationales.
It is an important aspect of any software architecture.

Quality Requirements

Quality requirements as scenarios, with quality tree to provide a high-level overview. The most important quality goals should have been described in section 1.2 (quality goals).
Should be documented as fitness functions and realized as automated tests.

Risk and Technical Debt

Known technical risks or technical debt. What potential problems exist within or around the system? What does the development team feel miserable about?
Risk management is part of any professional product development and shall be documented. Ideally, a good product developed with professionals has a very low technical debt.


Important domain and technical terms that stakeholders use when discussing the system. Also: translation reference if you work in a multi-language environment.
Static web page generator approaches create more legible, searchable and usable documentation. Paper-based documentation or wikis are a suboptimal way of describing a software product.

The arc42 approach is heavily influenced by their UML and RUP roots. This heritage is one major reason why this approach is not extensively taught in the course.

Bachelor students have attended formal training in UML and scientific diagramming notations such as C4 or BPMN. They can produce these artifacts before attending the SWAT course.

ISAQB Architecture Program

2021 09 02 cspa foundation

The SWAT lecture has similar theme weights as the ISAQB International Software Architecture Qualification Board foundation level training and certification [1].

The ISAQB foundation is kind of a laggard. Most of their trainings are for classical software and enterprise architecture. They have finally understood lately that agile is won the war how to develop digital products.

THe ISAQB programs teach skills in three areas: technological competence, methodical competence, and communicative competence.

The key points are:

  • The concept and meaning of software architecture

  • Tasks and responsibility for you as a software architect

  • Your role as a software architect in projects

  • State-of-the-art methods and techniques for the development of software architectures

The taught skills are:

  • How can you coordinate essential software architecture decisions with other project participants from the fields of requirements management, project management, testing and development?

  • How can you document and communicate software architectures based on architecture patterns and technical concepts?

  • How can you independently carry out the essential steps in designing software architectures for small and medium-sized systems?

2021 09 02 cspa agile

They have a specific module for agile software architecture:

  • Basics

  • Agile approach to architecture

  • Architecture requirements in agile projects

  • Designing architectures in a team

  • Reflection and feedback

  • Examples of agile architecture work

In this module, the participants learn how to design, develop and further develop software systems and architectures in accordance with agile principles. On the one hand, the module covers the application of agile principles and concepts to architecture work. On the other hand, expedient anchoring of architecture practices in an agile approach.

The development of architectures in projects with self-sufficient teams or shared responsibilities demands new skills and capabilities on the part of developers and architects. These in turn cover technical as well as methodical and communicative aspects, which are addressed here all theoretically and in practical exercises.

The learning goals for the ISAQB agile certification are:

Introduction to agile software architecture
  • Knowing and being able to explain the significance of agile ideas for architecture work.

  • Knowing the tasks involved in architecture development and how they are modified in the agile environment.

  • Being able to appropriately align architecture work to the specific problem and project.

  • Knowledge of agile tools for architecture work.

  • Knowledge of the capabilities for anchoring architecture as a cross-cutting aspect in agile organisations.

  • See What is Agile Architecture, Agile Approaches

The agile architecture approach
  • Being able to iteratively and agilely structure architecture work.

  • Knowledge of role models for architects in agile projects.

  • Knowledge of ways involving stakeholders in architecture work.

  • See Agile Approaches, Excellence for Architects

Architecture requirements in agile projects
  • Being able to formulate quality requirements appropriately for specific target groups.

  • Being able to use agile concepts for architecture requirements.

  • Being able to use iterative approaches for continuous definition of architecture requirements.

  • Being able to effectively organise joint management, evaluation and prioritisation of requirements.

  • Knowing and being able to explain urgency as a driving factor for architecture work.

  • See Agile Approaches, Functional Features

Designing and developing architectures in a team
  • Being able to use methods for making decisions in groups.

  • Being able to support groups and teams in reaching decisions.

  • Being able to create the necessary prerequisites for team decisions.

  • Being familiar with architecture concepts for promoting local decision-making capabilities.

  • Being familiar with methods for just-in-time architecture decisions.

  • Being familiar with ways of communicating architecture decisions in agile projects.

  • See Agile Approaches, Excellence for Architects

Reflection and feedback on architecture work in the agile context
  • Being familiar with techniques for joint reflection on architecture decisions.

  • Being able to find the reasons for specific architecture problems.

  • Being familiar with feedback capabilities from the implementation and able to attribute results to architecture objectives.

  • See Errors and Smells, Component Architecture

Examples of agile architecture work
  • Being familiar with and understanding examples of decision-making procedures in agile projects.

  • Being familiar with and understanding examples for agile architecture requirements.

  • Being familiar with physical characteristics of agile communication concepts.

  • Being able to understand the postponement of architecture decisions.

  • Being familiar with and understanding examples of agilely organised architecture groups.

  • See Excellence for Architects

Care was taken that all the above aspects are handled over the SWAT course. The main difference is the SWAT course has a more technical approach to agile architecture. Communication, team findings techniques and documentation are discussed in Agile Approaches, Architecture Documentation and Excellence for Architects.

Bachelor students have attended formal training in Scrum and had extensive team workshop to foster communication techniques.

Lessons Learnt


Principles need to be taught at the beginning. The students already know concepts such as KISS, SOLID, YAGNI from previous lectures.

They can seldom apply these principles in their own code or semester projects. Understanding why certain anti-patterns are often wrong is seldom observable.

You can only become a professional software architect if you are proficient in a technology stack. You shall be a craftsman about how to write industrial grade source code.

You know how to test it, deploy it, run it and maintain it. You shall have knowledge of the idioms for your programming language and software design patterns at the component level.

The students are motivated and eager to learn. It takes time to establish the capabilities of a professional programmer and component designer.

This time is missing in our SWAT lecture for the discussion of product software architecture themes.

We are now defining an overall path for all students to achieve craftsmanship over their bachelor curriculum. Students must write professional source code, master design at the component level, and understand agile techniques. Approaches such as clean code, test-driven development, refactoring and infrastructure as code shall be studied material.

Design and Architecture

Design concepts must be refined. The students understand concepts such as patterns, micro-architecture, layered architecture. They seldom formulate the technical and financial tradeoffs associated with a specific concept application [2].

Almost no student has experience with open source libraries. They used them on a daily basis and never looked at the source code, provided an improvement, or read the documentation.

We are trying to formulate an approach to improve achieved goals. We shall either build these concepts into project management lectures or in the semester theses.


[1] E. Evans, Domain-driven design. Addison-Wesley, 2004 [Online]. Available: https://www.amazon.com/dp/0321125215

[2] M. Fowler, Refactoring, First. Addision-Wesley, 1999 [Online]. Available: https://www.amazon.com/dp/B004PQQRK2

[3] N. Ford, R. Parsons, and P. Kua, Building Evolutionary Architectures: Support Constant Change, First. O’Reilly Media, 2017 [Online]. Available: https://www.amazon.com/dp/1491986360

[4] M. C. Feathers, Working Effectively with Legacy Code. Prentice Hall, 2004 [Online]. Available: https://www.amazon.com/dp/0131177052

[5] R. C. Martin, Clean Code. Prentice Hall, 2009 [Online]. Available: https://www.amazon.com/dp/0132350882

[6] R. C. Martin, The Clean Coder. Prentice Hall, 2011 [Online]. Available: https://www.amazon.com/dp/0137081073

[7] R. C. Martin, Clean Architecture. Pearson, 2017 [Online]. Available: https://www.amazon.com/dp/0134494164

[8] R. C. Martin, Clean Agile. Prentice Hall, 2020 [Online]. Available: https://www.amazon.com/dp/0135781868

[9] R. C. Martin, Clean Craftsmanship. Addison-Wesley Professional, 2021 [Online]. Available: https://www.amazon.com/dp/B095C16LSW

[10] V. Vernon, Domain-Driven Design Distilled. Addison-Wesley Professional, 2016 [Online]. Available: https://www.amazon.com/dp/B01JJSGE5S/

[11] V. Vernon, Implementing Domain driven Design. Addison-Wesley Professional, 2012 [Online]. Available: https://www.amazon.com/dp/B00BCLEBN8

1. The main difference is the course has weighted more heavily on examples and exercises. Students learn better when they practice the theory
2. Choosing a technical and financial tradeoff is the essence of engineer’s work. These tradeoffs are often formulated in architecture design records ADR.