Overview
Software architecture is the set of decisions that are expensive to change later: component boundaries, communication patterns, data ownership, deployment topology, and the tradeoffs among quality attributes like performance, scalability, security, and maintainability. These decisions shape every line of code that follows them, yet they are traditionally made early in a project when uncertainty is highest. The result is a paradox: the most consequential decisions are made with the least information.
This chapter reframes architecture as a discovery problem in the framework introduced in Chapter 1. The search space $S$ is the set of all feasible architectures for a given set of requirements. Each architecture is a labeled directed graph $G = (V, E)$ where vertices $V$ represent components and edges $E$ represent connectors (synchronous calls, async messages, shared data stores). The objective is not a single scalar but a vector of quality attributes $\mathbf{q} = (q_1, q_2, \ldots, q_k)$, making this a multi-objective optimization problem. The solution is not a single "best" architecture but a Pareto frontier: the set of architectures where no attribute can be improved without degrading another.
We will build tools that generate candidate architectures from requirements, score them against quality attributes using fitness functions, compute the Pareto frontier, and produce Architecture Decision Records (ADRs) that document the rationale for the chosen design. These tools extend the Discovery Workbench introduced in Chapter 6, connecting directly to the requirements pipeline from Chapter 13. By the end of the chapter, you will have a working Architecture Discovery Assistant that takes validated requirements as input and produces a Pareto-analyzed, ADR-documented architecture as output.
Prerequisites
You should have read Chapter 13: Discovery of Requirements for the requirement structures and traceability matrix that feed into architecture discovery. Familiarity with Chapter 9: Vibe Coding and Chapter 10: Prompting to Programming is assumed for the LLM-driven generation techniques. Background in graph theory (covered in Chapter 3) is helpful for the component-graph representations. No prior software architecture coursework is required; the chapter introduces all necessary concepts from first principles.
Learning Outcomes
- Distinguish and characterize four major architectural styles (layered, microservices, event-driven, hexagonal) in terms of their structural properties and quality-attribute profiles.
- Represent software architectures as directed component graphs and analyze them using NetworkX for coupling, cohesion, and modularity metrics.
- Define fitness functions that quantify quality attributes (performance, scalability, maintainability, security) and evaluate candidate architectures against them.
- Compute the Pareto frontier over a set of candidate architectures scored on multiple quality attributes, using both brute-force and efficient algorithms.
- Use LLMs to generate candidate architectures from requirements, with structured output and Mermaid/Structurizr diagram generation.
- Write and manage Architecture Decision Records (ADRs) that capture context, alternatives considered, tradeoffs, and rationale.
- Build a complete Architecture Discovery pipeline that generates, evaluates, selects, and documents architectures as a component of the Discovery Workbench.
Sections
14.1 Architectural Styles and Quality Attributes
Four canonical styles (layered, microservices, event-driven, hexagonal) as graph topologies. Quality attributes as measurable properties. Fitness functions that map architectures to quality scores. Architecture as a component graph: nodes, edges, coupling, cohesion, and modularity metrics computed with NetworkX.
14.2 AI-Assisted Architecture Generation
Using LLMs to generate candidate architectures from validated requirements. Structured output with Pydantic schemas. Visualization with Mermaid and Structurizr DSL. Multi-objective evaluation: scoring candidates, computing the Pareto frontier, and selecting the optimal tradeoff point.
14.3 Building Architecture Decision Records
Recipe: a complete pipeline that ingests requirements, generates three candidate architectures, evaluates them with fitness functions, computes the Pareto frontier, selects the optimal candidate, and produces a fully documented ADR. Integration with the Discovery Workbench.
Bibliography
Foundational Papers
The seminal roadmap paper that defined software architecture as a discipline, introducing the concepts of architectural styles, quality attributes, and the role of architecture in managing system complexity. Essential framing for this chapter.
Surveys the use of LLMs for recovering and generating software architectures from codebases and documentation. Demonstrates that LLMs can identify architectural patterns with accuracy comparable to expert architects.
A systematic review of methods for evaluating software architectures against quality attributes. Covers scenario-based (ATAM), metric-based, and model-based approaches, providing the theoretical basis for our fitness functions.
Books
A comprehensive guide to architectural styles, quality attributes, and decision-making. The architectural-characteristic star charts and style comparisons in Section 14.1 follow this book's framework.
Introduces fitness functions as executable tests for architectural quality attributes. The fitness-function concept in Section 14.1 is directly adapted from this book's framework.
Tools & Libraries
The graph analysis library used throughout this chapter for representing architectures as component graphs and computing coupling, cohesion, and modularity metrics.
A JavaScript-based diagram renderer that generates architectural diagrams from text descriptions. Used in Section 14.2 for rendering LLM-generated architecture visualizations.
An architecture-as-code tool implementing the C4 model. Provides a DSL for defining software architectures at multiple levels of abstraction, used alongside Mermaid for richer visualizations.
Used for defining structured architecture schemas that ensure LLM-generated candidates conform to well-formedness rules before evaluation.
Tutorials & Standards
The original proposal for lightweight ADRs. Defines the status/context/decision/consequences template used in Section 14.3.
The international standard for architecture descriptions. Defines viewpoints, views, and architecture decisions as first-class elements, grounding the formal treatment in this chapter.
The Architecture Tradeoff Analysis Method, the most widely used scenario-based evaluation approach. Our fitness-function framework automates and extends ATAM's core ideas.