Software Architecture

Overview

Software architecture is the set of significant decisions about the organization of a software system -- the selection of structural elements, their interfaces, composition, and the guiding principles that constrain design and evolution over time. Choosing the right architecture style is one of the highest-leverage decisions a team makes; it shapes every subsequent technical and organizational choice.

This skill covers how to reason about architecture styles, evaluate architecture characteristics (quality attributes), and make informed tradeoffs. For deep dives into specific styles, see the sub-skills below.

Canonical Works

The Monolith-to-Microservices Spectrum

Architecture is not a binary choice between monolith and microservices. It is a spectrum of modularity:

 Monolith                                                    Microservices
    |                                                             |
    |  Big Ball    Layered    Modular      Service-    Micro-     |
    |  of Mud      Monolith   Monolith     Based       services   |
    |                                                             |
    ◄─────────────────────────────────────────────────────────────►
    Less distributed                          More distributed
    Simpler operations                        Complex operations
    Easier consistency                        Eventual consistency
    Tighter coupling                          Loose coupling

Key insight (Richards & Ford): Move along the spectrum only when the pain of your current position exceeds the cost of the next step. Start simple; evolve when you have evidence.

Architecture Characteristics (Quality Attributes)

Architecture characteristics -- also called "-ilities" -- are the non-functional requirements that shape which style fits. They are inherently in tension; optimizing one often degrades another.

Identifying Driving Characteristics

Not every characteristic matters equally. Richards & Ford recommend identifying the top 3-5 driving characteristics for a system and using those to select an architecture style.

Architecture Style Comparison

Architecture Decision Records (ADRs)

Every significant architecture decision should be captured in an Architecture Decision Record. ADRs provide context for future developers about why a decision was made, what alternatives were considered, and what tradeoffs were accepted.

See: specs/documentation/adr for ADR templates and practices.

ADR structure (Michael Nygard format):

• Title -- Short noun phrase (e.g., "Use PostgreSQL for order data")
• Status -- Proposed, Accepted, Deprecated, Superseded
• Context -- The forces at play, the problem, the constraints
• Decision -- What was decided and why
• Consequences -- What becomes easier, what becomes harder

Architecture Decision Process

1. Identify the driving characteristics -- What are the top 3-5 quality attributes?
2. Identify the domain partitioning -- How does the domain decompose? (see dev/architecture/domain-driven-design)
3. Select a candidate style -- Use the comparison table above to narrow options.
4. Evaluate tradeoffs -- Every style has strengths and weaknesses. Make tradeoffs explicit.
5. Record the decision -- Write an ADR capturing context, decision, and consequences.
6. Validate with fitness functions -- Define measurable criteria that the architecture must satisfy over time.

Common Anti-Patterns

• Accidental architecture -- No deliberate style; the system evolves into a Big Ball of Mud.
• Resume-driven architecture -- Choosing microservices (or any style) because it looks good on a resume, not because the problem demands it.
• Architecture by analogy -- "Netflix uses microservices, so we should too." Your context is not Netflix's context.
• Ignoring the First Law of Software Architecture -- "Everything in software architecture is a tradeoff" (Richards & Ford). If you think you found something that isn't a tradeoff, you haven't identified the tradeoff yet.

Best Practices

• Start with the simplest architecture that meets your driving characteristics. Evolve when evidence demands it.
• Make architecture decisions explicit and documented (ADRs).
• Architecture is not a one-time activity -- it is continuous. Revisit decisions as the system and context evolve.
• Align architecture boundaries with team boundaries (see Conway's Law and the Inverse Conway Maneuver).
• Use fitness functions to objectively measure whether the architecture meets its goals over time.
• Understand that the "best" architecture depends on your specific context: team size, domain complexity, scale requirements, and organizational structure.

Sub-Skills

• dev/architecture/microservices -- Service decomposition, inter-service communication, saga patterns
• dev/architecture/monoliths -- Modular monolith, monolith-first strategy, Strangler Fig migration
• dev/architecture/well-architected -- AWS, Azure, and GCP well-architected frameworks
• dev/architecture/event-driven -- Event-driven architecture, event sourcing, CQRS
• dev/architecture/domain-driven-design -- Bounded contexts, aggregates, strategic and tactical DDD
• dev/architecture/hexagonal -- Ports and adapters, onion architecture, dependency inversion