Driving Better Architecture Decisions with Architecture Principles

A common challenge in modern software architecture is how to empower people to make architectural decisions while keeping them aligned with the overall goals and priorities of the system.

Architectural principles are a deceptively simple idea which helps us to achieve this.

Principles provide actionable goals, constraints and priorities, with clear rationale, that allow their applicability and importance to be quickly understood. This gives people the context they need to make good, aligned decisions.

In this talk I will introduce the idea of an architecture principle, discuss what makes a good principle and how to capture it clearly, and show how they relate to architectural decisions to help teams make good decisions that solve their immediate problem but also preserve the technical integrity of the system.

I also briefly discuss what this means when we have mixed human and AI agent teams.

Transcript

1. DRIVING BETTER ARCHITECTURE DECISIONS WITH ARCHITECTURE PRINCIPLES EOIN WOODS ARTECHRA
2. Eoin Woods Independent consultant (software architecture, CTO) • Co-author of three Software Architecture books and many other things too • 10 years as CTO in delivery consultancy • 10 years in capital markets • 10+ years in software product engineering ADDRESSING ENERGY EFFICIENCY IN SYSTEM DESIGN: A JOURNEY FROM ARCHITECTURE TO OPERATION EOIN WOODS A thesis submitted in partial fulfilment of the requirements of the University of East London for the degree of Doctor of Philosophy December 2018
3. SOME COMMON ARCHITECTURE CHALLENGES Explaining unifying rationale for architecture and design decisions Maintaining knowledge over time Empowering teams to make good decisions while staying aligned Creating minimal but valuable documentation Ensuring AI agents contribute without chaos
4. PRINCIPLES AND DECISIONS Architecture principles and decisions are simple techniques that allow us to capture knowledge, align decision making and even cajole AI-tools into doing what we want them to do!
5. PRINCIPLES AND DECISIONS
6. PRINCIPLES AND DECISIONS Principles Decisions Our priorities and beliefs Guardrails for guiding decisions A link from requirements to decisions How and why our system works Our architectural journey (tradeoffs) Guidance on looking after the system Together they are an elegant and lightweight solution for capturing architectural knowledge and aligning architecture work
7. ARCHITECTURE PRINCIPLES A Principle a fundamental truth or proposition serving as the foundation for belief or action [OED] An Architecture Principle a declarative statement made with the intention of guiding architectural design decisions in order to achieve one or more architectural qualities of a system
8. A SIMPLE ARCHITECTURE PRINCIPLE Name Availability is Key Description For every part of the system that supports customer journeys, particularly transaction journeys, availability is the key quality attribute and is prioritised over everything else apart from security. Rationale We lose money, reputation, operational efficiency and customer satisfaction when systems are not available and it prevents customers buying what they want to buy. Implications We need to design carefully to achieve resilience but also to avoid secondary problems when achieving resilience. Example Should components lose communication with each other, they should continue processing as much as possible using cached data or partial data, even if this means reconciliation or compensating transactions are needed later.
9. ARCHITECTURAL DECISIONS An architectural decision is … They tend to be the decisions that are difficult to change later A pertinent design decision that addresses an architecturally significant requirement ISO/IEC/IEEE 42010 (2022)
10. A SIMPLE ARCHITECTURAL DECISION Name Data Store per Service Description Each service owns its data exclusively; no service may directly access another service's data store. Rationale • Shared data stores create hidden coupling between services, making them difficult to evolve, scale, or deploy independently. • A service's data store schema is an implementation detail — exposing it to other services turns that detail into a contract, making change difficult. Implications • Cross-service data access through APIs or events, not data store queries • Each service's storage technology can be chosen to fit its needs (but may lead to increased operational complexity) • Schema changes do not require cross-team coordination
11. PRINCIPLES HELP TO ALIGN TEAMS Goal Requirement Principle Decision
12. EXAMPLE: DEALING WITH REGULATION Goal: allow product to be sold into regulated industries Requirement: allow deployment on premise and to public cloud platforms Principles: 1. Avoid cloud specific unique services 2. Use generic data models (RDBMS, Document DB) minimising db specific dependencies in schemas and queries Decisions: 1. Initially deploy to AWS 2. Do not use unique AWS services (e.g. DynamoDB), ensuring that services used are generally available elsewhere 3. Use RDS Postgres for storage, accessed via our LibStore Guidance Rationale
13. WORKING WITH ARCHITECTURE PRINCIPLES
14. USEFUL TYPES OF PRINCIPLE Guide Towards a Goal “Wherever possible use a single visitor logon for all user interfaces within our consumer ecosystem” Indicate a Preference Avoid Technical Problem Encourage a Practice “We prefer 3rd party data formats, over in-house data formats, over custom data formats” “Do not bind UIs to service data models. For example use DTOs and proxy libraries” “Our software must always be deployable at the end of an iteration” Philosophy or Belief “Abstractions live longer than details” (Hunt & Thomas - The Pragmatic Programmers)
15. DEFINING A PRINCIPLE Name A clear, concise and ideally memorable name that captures the intent of the principle Description A full description of what the principle is trying to communicate, be that preference, guidance, problem avoidance and so on Rationale Why the principle makes sense, why we want to guide people in this way Applicability Where the principle applies and, if not obvious, where it does not Implications The known and accepted tradeoffs of adopting this principle Example If possible, provide a simple example of following the principle that brings it to life
16. ANOTHER EXAMPLE Name Prioritise Standardisation of Message Protocols Description We prefer to use industry protocols for messaging, where this isn’t possible we use well defined in-house ones, only in the last resort do we use local ad-hoc protocols Rationale Minimise concept (re)definition, maximise software reuse, align with market and organisational models and conventions, maximise future integration options, support flexible organisational structure Applicability All inter-system financial transactions across the Global Markets IT Group. Implications Teams need to understand the options; time needs to be taken to understand new protocols if needed; less flexibility in some cases Example For the main Front-Office to Risk trade feed, we decided to use the FIX protocol for all business where possible, where FIX cannot be used, use the Global Equities standard transaction messages, for the remaining (small number of) cases, create an ad-hoc point-to-point extension to FIX to encode these trades.
17. WHERE DO PRINCIPLES COME FROM? Goals & Requirements Principles to guide towards strategy, principles which reflect priorities in requirements Industry Norms & Regs General principles from your industry (e.g. the importance of safety or accessibility, the need for data traceability, …) Tech Leads The people with the “architecture in their heads” know where it is likely to be important to provide guidance Painful Experience What do we want to avoid doing again?
18. PROPERTIES OF GOOD PRINCIPLES Constructive Stated for a purpose, useful guide for decision making Reasoned Rational, logical, consistent Well Articulated Comprehensible by all of the necessary stakeholders Testable Can you check if you’ve followed it and spot exceptions? Significant Not just a truism; would the opposite ever be true? (Nick Rozanski)
19. PROPERTIES OF GOOD PRINCIPLES Constructive “Prefer flexible data models to allow constant change and ..” rather than “Don’t use relational databases” Reasoned “Minimise personal data collection as privacy is an important concern” rather than “Don’t collect unnecessary data” Well Articulated “Predictable floating-point calculations are essential so we …” rather than ”We encode all data according to IEEE 754” Testable “Authentication mechanisms must avoid common password risks such as …” rather than “User authentication must be secure” Significant ”We prioritise the needs of occasional users over …” rather than “The system must be usable by inexperienced users”.
20. WORKING WITH ARCHITECTURAL DECISIONS
21. ADRs: RECORDING DESIGN DECISIONS ¡ Design decisions are a communication technique (as well as a historical record) ¡ A common format helps to communicate clearly, minimises cognitive load, helps to avoid things being forgotten ¡ There are many, many (… many!) formats for Architecture Decision Records https://github.com/joelparkerhenderson/architecture-decision-record
22. No shortage of opinions on what an ADR is or how to create one!
23. MINIMAL ADR (MICHAEL NYGARD) https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions Name Clear unique name that briefly communicates the crux of the decision Status Whatever is needed, for example: proposed / agreed / implemented / superseded / withdrawn Context The situation in which we made this decision and what were we trying to achieve by making it Decision A clear definition of the decision in technical terms (as long as it needs to be) Consequences What are the tradeoffs from this decision? Why do we think we have the right decision? What gets easier? What gets harder?
24. COMPREHENSIVE ADR (TYREE AND AKERMAN) A really comprehensive version could include: • Name • Problem • Status • Decision • Group • Assumptions • Constraints • Viable Options • Reasoning • Consequences (Trade-offs) • Related Decisions • Related Requirements • Related Artefacts • Related Principles • Notes Architecture Decisions: Demystifying Architecture, Jeff Tyree and Art Akerman, IEEE Software, March/April 2005 https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/locales/en/templates/decision-record-template-by-jeff-tyree-and-art-akerman
25. PROPERTIES OF AN EFFECTIVE DECISION Named A good name so you can refer to it easily and know what it is about Well Described A comprehensive, clear description to communicate the essential points Practical, Actionable Practical in the intended context, solves a problem, actionable by delivery teams in their current working environments. Logical, Justified Well reasoned with the reasoning explained as part of its definition Contextual Takes current context into account, actionable in that context Aligned Following in the guidance in our principles (or if not, flag this), compatible with the other decisions we have already made Testable How will we know if we followed the advice in this decision?
26. PROPERTIES OF AN EFFECTIVE DECISION Named “Data store per service” rather than “Separate databases” Well Described Get someone else to read it and explain it back to you … challenge every sentence but don’t be afraid to make it long enough to explain the point. Practical, Actionable Make sure the decision solves a problem, give advice to how to apply it, give an example of it in use Logical, Justified Make sure that the rationale is clear and makes sense. Challenge yourself from different perspectives. Ask someone else to challenge it. Contextual Does it work, is it relevant in the current context? Or something for later? Aligned Is it compatible with the other decisions? And the principles? Testable Think through how you would test for it, could you do it automatically?
27. A PRINCIPLE TO GUIDE A DECISION … Name Prefer API-First Design Description We want to structure our software using formal APIs and treat APIs as products in their own right, with clear contracts, versioning strategies, tests and consumer- focused design. Service APIs should be designed and published as early as possible. Rationale • Creates clear contracts and responsibilities for high cohesion and low coupling • Facilitates early feedback on interface design • Supports automated testing and API mocking • Consistency and developer experience Implications • API documentation will be required and must be kept current • API design reviews must be part of the development process • API change and deprecation policies must be established and followed • Need policy and practices for breaking changes to APIs (“Applicability” and “Example” omitted for space reasons)
28. … A RELATED DECISION Name Adopt Microservices Architecture with Domain-Driven Design Status Proposed Context The need to support rapid feature development, independent team scaling, and varying load patterns across different business capabilities Description We will implement a microservices architecture with • services bounded by domain contexts (Product, Order, Payment, User). • services will be independently deployable • each service has its own database • services communicate via well defined, versioned APIs (via OpenAPI, AsyncAPI) • APIs can be synchronous REST APIs or asynchronous message queues. Consequences Positive: independent scaling; teams can deploy features without coordinating releases; technology choices can vary; failures are isolated to individual services Negative: operational complexity; distributed system complexities; need for sophisticated monitoring and tracing; data separation across services Prefer API-First Design Name We want to structure our software using formal APIs and treat APIs as products in their own right, with clear contracts, versioning strategies, tests and consumer- focused design. Service APIs should be designed and published as early as possible. Description • Creates clear contracts and responsibilities for high cohesion and low coupling • Facilitates early feedback on interface design • Supports automated testing and API mocking • Consistency and developer experience Rationale • API documentation will be required and must be kept current • API design reviews must be part of the development process • API change and deprecation policies must be established and followed • Need policy and practices for breaking changes to APIs Implications
29. WHEN PRINCIPLES AND DECISIONS COLLIDE ¡ Sometimes principles & decisions diverge ¡ when a principle is contradicted, this needs to be justified ¡ i.e. benefits have to outweigh the costs ¡ Doesn’t (necessarily) reduce usefulness of principles ¡ reason for breaking a principle is valuable design information ¡ many violations (>3?) signal the need to revisit the principle ¡ noting the violation signals a non-standard decision Photo by Marco Kaufmann on Unsplash
30. PRINCIPLES AND DECISIONS TODAY … but today we have a new challenge when aligning teams … how to align teams of humans and AI agents Principles and decisions are a proven and valuable technique for aligning software engineering teams …
31. PRINCIPLES AND DECISIONS IN AN AI WORLD
32. ARCHITECTURAL ALIGNMENT WITH AI ¡ Traditionally we have had human teams ¡ We aligned them with meetings, code reviews, design debates and chats over coffee Credit: Google Gemini 3.5 Flash
33. ARCHITECTURAL ALIGNMENT WITH AI Credit: Google Gemini 3.5 Flash ¡ Today we have mixed AI and human teams ¡ AI agents don’t drink coffee or take part in team debates about design decisions ¡ We need a new way to align our teams ¡ Traditionally we have had human teams ¡ We aligned them with meetings, code reviews, design debates and chats over coffee
34. ARCHITECTURAL ALIGNMENT WITH AI But AI agents can “read” principles and ADRs Principles and decisions can align humans and AI agents
35. PRINCIPLES & DECISIONS AS AI CONTEXT ¡ Principles and decisions are precise textual descriptions to guide the design process ¡ Exactly what an AI-tool can consume
36. HELPING AI TOOLS TO GET ALIGNED ¡ Describe principles as short actionable rules ¡ Summarise ADRs as decisions and implications ¡ Only include key relevant ADRs ¡ Be explicit about intent (don’t rely on implication) ¡ Use CLAUDE.md files (e.g.) in subdirs to limit scope ¡ Tell the tools explicitly to use the guidance
37. HUMAN PRESENTATION … Cloud-Portable Data Storage Name All persistent storage must use technology that is not specific to any single cloud provider. Queries and schemas must be written in standard SQL (Postgres dialect). Cloud-specific data services must not be used directly from application code. Description Some customers need private cloud deployment, depending on cloud-native data services makes this impossible or very costly to retrofit. The cost of maintaining portability is low; the cost of retrofitting it is very high. Rationale All services reading from or writing to persistent storage. Applicability Cloud-native services with compelling operational advantages — DynamoDB's auto- scaling, BigQuery's analytics — are unavailable for application data storage. Implications A team evaluates DynamoDB for a new consent records service but uses Postgres instead. When the product is later sold to an organisation requiring private-cloud, deployment the repository is retargeted to a local Postgres instance. Example Use Postgres-Compatible Relational Storage for All Application Data Name Agreed Status We need to support deployment to cloud and private-cloud. Several cloud-native options offer attractive operational simplicity on AWS but would couple our application to AWS. Context All application services will use Postgres as their relational data store, accessed via a repository interface in the domain layer. On AWS we use AWS RDS for Postgres and avoid any AWS extensions or APIs. Decision Storage is cloud-portable and on-premise deployable with a connection string change; business logic is decoupled from infrastructure. Negative: we forgo cloud-specific database features, the team must operate or configure Postgres; the abstraction layer adds a small amount of design overhead. Consequences
38. … CAN BE SUMMARISED FOR MACHINES … ## A example CLAUDE.md file ## Architecture Principles ... **AP-03 Cloud-Portable Data**: Use only standard SQL (Postgres dialect) for queries. No DynamoDB, no cloud-specific extensions. Ensure software is deployable on-premise. ... ## Key Architectural Decisions **ADR-012: Postgres-compatible storage for all application data** (Status: Agreed) All persistent data must use Postgres via a repository interface in the domain layer. Full ADR in docs/adr/adr012-postgres-storage.md ...
39. … AND PUT INTO THE CODELINE repo/CLAUDE.md src/ api/CLAUDE.md data/CLAUDE.md docs/adr/ Summaries of project-wide principles & key ADRs Summaries of API-specific principles & key ADRs Summaries of storage-specific principles & key ADRs Full Principle and ADR files for humans, referenced from CLAUDE.md files
40. TO CONCLUDE
41. PRINCIPLES HELP TO ALIGN TEAMS Goal Requirement Principle Decision
42. SOME COMMON ARCHITECTURE CHALLENGES Explaining unifying rationale for architecture and design decisions Maintaining knowledge over time Empowering teams to make good decisions while maintaining alignment Creating minimal but valuable documentation Ensuring AI agents contribute without chaos
43. TACKLING COMMON ARCHITECTURE CHALLENGES Explaining unifying rationale for architecture and design decisions Maintaining knowledge over time Empowering teams to make good decisions while staying aligned Creating minimal but valuable documentation Ensuring AI agents contribute without chaos Decisions record locale rationale, principles provide the unifying rationale across the system Principles and decisions can be a versioned knowledge base of why things are the way they are Principles guide decision making in context, decisions are the history of what others have done (and why) Principles and decisions contain the minimum information needed As text they can guide AI agents to avoid inconsistency and chaos
44. REFERENCES
45. Thank You – Questions? Eoin Woods Artechra eoin.woods@artechra.com www.eoinwoods.info