Driving Better Architecture Decisions with Architecture Principles

(This updated version of the talk was presented at ITARC 2026 in Stockholm in September 2026)

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.

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 shared understanding across team members
4. … AND A NEW COMPLICATION We are used to having to communicate, guide and align human team members … … now we have to include AI agent team members too who create some new and unique problems.
5. 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!
6. PRINCIPLES AND DECISIONS
7. A POSSIBLE SOLUTION Principles Decisions Priorities and beliefs Guardrails for guiding decisions 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
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. 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
10. PRINCIPLES HELP TO ALIGN TEAMS Goal Requirement Principle Decision
11. EXAMPLE: DEALING WITH REGULATION Goal: allow product to be sold into regulated industries io n id a n ce 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 R at Gu Principles: 1. Avoid cloud specific unique services 2. Use generic data models (RDBMS, Document DB) minimising db specific dependencies in schemas and queries a le Requirement: allow deployment on premise and to public cloud platforms
12. WORKING WITH ARCHITECTURE PRINCIPLES
13. 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 “We prefer 3rd party data formats, over in-house data formats, over custom data formats” Avoid Technical Problem “Do not bind UIs to service data models. For example use DTOs and proxy libraries” Encourage a Practice “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)
14. DEFINING A PRINCIPLE Name Description Rationale Clear, concise, memorable The advice or guidance to be communicated Why is this important? Why does it make sense? Applicability Where does this apply? (And where not) Implications What are the trade offs of accepting this principle? Example Short realistic example to illustrate in context
15. 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.
16. 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 reporting traceability, …) Tech Leads Painful Experience The people with the “architecture in their heads” know where it is likely to be important to provide guidance What do we want to avoid doing again?
17. PROPERTIES OF GOOD PRINCIPLES INSTEAD OF … SAY … Constructive “Don’t use relational databases” “Prefer flexible data models to allow constant change and …” Reasoned “Don’t collect unnecessary data” “Minimise personal data collection as privacy is an important concern” Well Articulated “We encode all data according to IEEE 754” “Predictable floating-point calculations are essential so we …” Testable “User authentication must be secure” “Authentication mechanisms must avoid common password risks such as …” Significant “The system must be usable by inexperienced users” “We prioritise the needs of occasional users over …” (originally from Nick Rozanski)
18. WORKING WITH ARCHITECTURAL DECISIONS
19. 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
20. No shortage of opinions on what an ADR is or how to create one!
21. MINIMAL ADR (MICHAEL NYGARD) 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 much detail as it needs to have) Consequences What are the tradeoffs from this decision? Why do we think we have the right decision? What gets easier? What gets harder? https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions Alternatively, a very comprehensive ADR format can be found in: 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
22. PROPERTIES OF AN EFFECTIVE DECISION Effective Name Does the name say what was decided? “Data store per service”, not “Separate databases” Well Described Can someone else read it and explain it back to you accurately? In particular are the implications and trade offs clear? Practical & Actionable Does it say how to apply it, with an example of it in use? Logical & Justified Is the rationale clear? Has someone else challenged it? Contextual Is it relevant now … or something for later? Aligned Is it compatible with our principles and our other decisions? Testable How would we check it was followed? Could we automate that?
23. 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 consumerfocused 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)
24. … 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
25. COMMON PROBLEMS AND SOLUTIONS Too many Too few Truisms Forty principles nobody can recall; an ADR for every library choice Decisions oten made without enough context, when reasoning isn’t clear there is little to refer to “The system must be usable” Would anyone ever disagree? Start with 6–8 principles, perhaps 1012 decisions. Make them significant. Write the ADR the day you decide and publish it, write enough principles to guide key decisions Would the opposite ever be true? If not this isn’t a useful guide ADRs diverging from principles Outdated Not owned by the people affected “Performance beats simplicity” Perhaps true in 2015, still obeyed today One or more ADRs knowingly violate a principle If imposed centrally often either ignored or actively cause problems The danger is following blindly so reconsider when the context changes Not necessarily a failure can be a signal. Is the principle wrong, or is it just being ignored? Decisions belong as close as possible to those affected so minimise centrally defined principles and decisions Most of these are straightforward to fix once recognised and agreed
26. PRINCIPLES AND DECISIONS Principles and decisions are a proven and valuable technique for aligning software engineering teams … … but today we have a new challenge when aligning teams … how to align teams of humans and AI agents
27. PRINCIPLES AND DECISIONS IN AN AI WORLD
28. 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
29. ARCHITECTURAL ALIGNMENT WITH AI ¡ Traditionally we have had human teams ¡ We aligned them with meetings, code reviews, design debates and chats over coffee ¡ 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 Credit: Google Gemini 3.5 Flash
30. ARCHITECTURAL ALIGNMENT WITH AI But AI agents can “read” principles and ADRs Principles and decisions can align humans and AI agents
31. PRINCIPLES & DECISIONS AS AI CONTEXT ¡ Principles and decisions are structured textual descriptions guiding the design process … and so can be consumed by AI-tools
32. … SUMMARISED FOR THE MACHINES # CLAUDE.md (or AGENTS.md) Short, actionable rules ## Architecture Principles **AP-03 Cloud-Portable Data**: use standard SQL (Postgres dialect) only, and generic data models. The system must deploy on-premise and on cloud. Say what to do, not just what to avoid ## Key Architectural Decisions **ADR-012 Postgres-compatible storage** (Agreed): all persistent data goes through a repository interface in the domain layer. Full ADR: docs/adr/adr012-postgres.md Decision + implication ## Using this guidance Read the ADRs above before you change data access code. Summarised, with a pointer to the full ADR for humans Tell the tool to use it And keep it to the decisions that constrain this code
33. VERIFY: GUIDANCE IN, CHECK THE OUTPUT Specification Verification Pipeline Code AI Code Gen Agent Principles & Decisions Testable principles and decisions can be realised in the verification pipeline (“keep the agent honest”) • • • • • Unit tests Lint checks Fitness functions Static Analysis Quality Attribute Tests
34. TO CONCLUDE
35. TACKLING THE COMMON ARCHITECTURE CHALLENGES Explaining the unifying rationale Decisions only record rationale in one place Principles provide rationale across the system and decisions Maintaining knowledge over time A versioned record of why the system is the way it is Can be versioned and stored with the code Empowering teams, keeping alignment Principles guide when making a decision Past decisions show what others did, and why Minimal but valuable documentation Minimal amount of text that still contains the knowledge AI agents contributing without chaos Text that people and agents can both read Add checks to prove that they did and followed the guidance
36. WHERE TO START ON MONDAY (or … Wednesday) 1 2 3 4 Write down what you already believe Record the next decision Summarise ADRs and Principles with the code Check the ones that matter the most Six to eight principles your team agrees and acts on but has never written down Create an ADR, on the day you make the decision, in the simplest format possible Principles and key decisions in the agent file, pointing at the full versions Take the principle you would least like broken, and make it a test, add an automated check for a critical decision None of this needs a programme, a tool or a senior manager’s permission.
37. REFERENCES
38. Thank You – Questions? Eoin Woods Artechra eoin.woods@artechra.com www.eoinwoods.info