Software Architecture

1Concept / Definition

Software architecture is the set of significant structures and decisions of a software system: its elements, their relationships and properties, and the principles guiding its design and evolution — significant because they shape quality attributes and are costly to change.

2Why It Exists

Systems too large for one person's head need a shared, deliberate organisation. Without it, structure emerges accidentally from thousands of local decisions, and qualities such as performance, availability and modifiability become unpredictable. Architecture makes the important decisions explicit, early enough to matter and visible enough to be governed.

3Core Concepts

3.1 Definition

3.2 Architecture vs design

3.3 Architecture vs implementation

// Architecture made visible in implementation: module boundaries in a modular monolith
@ApplicationModule(displayName = "Orders",
                   allowedDependencies = { "catalog::api", "shared" })
package com.shop.orders;
 
// Verified on every build — architecture, not wishes
@Test
void modulesRespectBoundaries() {
    ApplicationModules.of(ShopApplication.class).verify();
}

3.4 Architectural structure

3.5 Architectural behavior

4How It Works Internally — Significance

4ADeep Dive — Architecture Erosion and Drift

// ArchUnit: layered architecture as an executable rule
@ArchTest
static final ArchRule layers = layeredArchitecture().consideringAllDependencies()
        .layer("API").definedBy("..api..")
        .layer("Application").definedBy("..application..")
        .layer("Domain").definedBy("..domain..")
        .layer("Infrastructure").definedBy("..infra..")
        .whereLayer("API").mayNotBeAccessedByAnyLayer()
        .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Infrastructure");

5APIs / Features / Syntax

6Practical Examples

6.1 The "simple" database choice

A team chose a document database for orders "because JSON is easy". Two years later reporting, transactions across orders and payments, and BI tooling all fought the choice; migration took nine months. The decision was architectural but was treated as a design detail.

6.2 Architecture discovered, not designed

A monolith grew for eight years without explicit structure; every change touched 20 packages. Recovering the implicit architecture with dependency analysis revealed three cyclic clusters, which became the first targets for modularisation.

6.3 Worked example — classify ten decisions

Scenario. At the kick-off of ShopNow's new order platform, the team had a list of ten open decisions and only one architect. They needed to know which decisions deserved architecture review and which teams could make on their own.

Walkthrough. The architect classified each decision by its scope, its effect on quality attributes and its cost of reversal. Event-driven integration, the choice of Kafka and multi-region deployment affect every service and are expensive to undo, so they are architecture. Topic naming conventions are design: they matter, but can be changed with moderate effort. Aggregate boundaries sit on the line between the two, because they shape data ownership. Using Lombok is an implementation detail that any team can decide.

Result. Only four of the ten decisions went to the architecture board; the rest were delegated with guidelines. Review meetings became shorter and teams stopped waiting for approvals they did not need.

Takeaway. Classify decisions explicitly by significance. Spend architecture effort on decisions that are wide in scope, shape quality attributes and are costly to reverse, and delegate everything else with clear guidance.

6.4 Worked example — structures of an order platform

Scenario. A new engineer asked, "What is the architecture of the order platform?" One senior developer described packages, another described services and Kafka, and a third described AWS regions and teams. All three were right, which confused the new engineer further.

Walkthrough. Each answer described a different structure of the same system. The module structure shows how code is organised: orders, payments, catalog and shared modules. The component-and-connector structure shows runtime elements and how they communicate: a REST gateway, services, Kafka and PostgreSQL. The allocation structure maps software to environments and people: EKS clusters in the Mumbai region and three owning teams. Each structure answers different questions, such as where to change code, how requests flow, or who to call during an incident.

Result. The team documented the platform with one view per structure, linked together. New engineers now read the three views in their first week and understand the system far faster.

Takeaway. No single diagram describes an architecture. Document at least the module, runtime and allocation structures, and say explicitly which one a diagram shows.

6.5 Worked example — behaviour under failure

Scenario. ShopNow's checkout called the payment service synchronously and published order events directly to Kafka. Nobody had specified what should happen when either dependency failed, until both failed during a sale.

Walkthrough. The architect wrote down the intended behaviour for each failure before changing any code. If payments respond slowly, checkout waits at most 2 seconds, marks the order PENDING, tells the customer that payment is being confirmed, and retries asynchronously. If Kafka is unavailable, events are written to an outbox table in the same transaction as the order, and a relay publishes them when Kafka recovers.

resilience4j:
  timelimiter:
    instances:
      payments: { timeoutDuration: 2s }
  retry:
    instances:
      payments: { maxAttempts: 3, waitDuration: 500ms }
# Order events: written to the outbox table in the order transaction,
# published to Kafka by a relay (Debezium or a scheduled publisher)

Result. At the next sale, a slow payment provider produced pending orders that completed within minutes instead of failed checkouts, and a short Kafka outage caused no lost events.

Takeaway. Failure behaviour is part of the architecture. Design it explicitly for every important dependency, write it down, and test it, rather than discovering it in production.

6.6 Worked example — cost of change estimate

Scenario. A product manager asked why the architects spent days debating a database split when renaming a class "takes a minute". He wanted to understand why some changes were treated so differently.

Walkthrough. The architect estimated the cost of three changes of different significance. Renaming a class touches one code base and takes minutes with IDE support. Changing a module boundary means moving code and data, changing interfaces and updating tests, which takes days or weeks. Splitting a shared database requires data migration, new APIs or events, coordination between teams and careful roll-out, which takes months.

Result. The estimate made the reason for careful review obvious: decisions that are cheap to change can be made quickly and fixed later, while decisions that take months to reverse deserve analysis up front.

Takeaway. Use cost of change as the practical test of architectural significance. Make cheap decisions quickly, and invest analysis only where reversal is expensive.

6.7 Worked example — Modulith documentation

@Test
void writeDocumentation() {
    new Documenter(ApplicationModules.of(ShopApplication.class))
            .writeModulesAsPlantUml()
            .writeIndividualModulesAsPlantUml();
}

Scenario. ShopNow's architecture diagrams were drawn by hand and were always out of date. Within months of each redesign, the diagrams no longer matched the modules in the code.

Walkthrough. The team used Spring Modulith, which already knows the application's modules and their dependencies. A test class creates an ApplicationModules model from the main application class and passes it to the Documenter, which writes a PlantUML diagram of all modules plus one diagram per module showing its dependencies and published events. The test runs in every build, and the generated files are published with the project documentation.

Result. Diagrams are regenerated on every build, so they always match the code. When a new dependency appeared between modules, it showed up in the diagram immediately and was discussed in code review.

Takeaway. Generate structural documentation from the code wherever possible. Diagrams that cannot drift are worth more than polished ones that quietly go out of date.

6.8 Worked example — decisions hidden in code

Scenario. During a design review of an older service, the architect found that the documented architecture said "services communicate through events", but the code told a different story.

Walkthrough. Several code patterns revealed architectural decisions nobody had recorded. A @Transactional method that made REST calls to other services implicitly assumed a distributed transaction that did not exist. Direct SQL against another service's schema meant the services were integrated through a shared database. Static singletons holding configuration assumed a single deployment per JVM and made multi-tenant deployment impossible.

// Hidden decision: the payment call is NOT rolled back if the insert fails
@Transactional
public Order place(Cart cart) {
    Order order = orders.save(Order.from(cart));
    paymentClient.charge(order.id(), order.total());   // remote call inside DB tx
    return order;
}

Result. Each smell was recorded as an architectural decision, either accepted with an ADR or scheduled for correction. The REST-in-transaction case was replaced by an outbox and a saga.

Takeaway. Architecture lives in code as much as in documents. Review code for smells that reveal unrecorded decisions, and make each one explicit: accept it with an ADR or fix it.

6.9 Worked example — quality attributes shape structure

Scenario. ShopNow's quality goals said the catalogue must handle ten times today's reads, checkout must stay available during partial outages, and pricing rules must change weekly without risk.

Walkthrough. The architect traced each quality attribute to a structural decision. Scalable catalogue reads led to a separate read model backed by a cache, so reads never touch the transactional database. Available checkout led to asynchronous side effects, so emails, loyalty points and analytics happen through events after the order is saved. Modifiable pricing led to an isolated pricing module with its own tests and deployment, so rule changes cannot break other areas.

Result. Each structure in the architecture could be justified by a named quality goal, and the reviews focused on whether each structure actually achieved its goal.

Takeaway. Derive structure from quality attributes, not from fashion. For every major structural element, you should be able to name the quality goal it serves.

6.10 Worked example — architecture in a small system

Scenario. A team of three developers building an internal expense tool said their system was "too small to have an architecture" and skipped any design discussion.

Walkthrough. Even this small tool had a handful of significant decisions: the web framework, the database, how it is deployed and how users authenticate. Within six months, the choice of a shared database with the HR system, made casually, meant every HR schema change broke the expense tool, and the custom login had to be replaced by company single sign-on under audit pressure.

Result. A one-hour discussion at the start, recorded in two short ADRs, would have avoided both problems. The team now records the few significant decisions in every new project, however small.

Takeaway. Every system has an architecture, either intended or accidental. Small systems need few architectural decisions, but those few still deserve to be made deliberately and written down.

6.11 Worked example — enforcing no cycles

@ArchTest
static final ArchRule noCycles = slices().matching("com.shop.(*)..")
        .should().beFreeOfCycles();

Scenario. ShopNow's monolith had developed dependency cycles between packages: orders depended on payments, which depended on customers, which depended on orders. Every change rippled unpredictably.

Walkthrough. The team added an ArchUnit rule that treats each top-level package under com.shop as a slice and requires the slices to be free of cycles. Existing violations were recorded in a freeze file, so the build passes for known cycles but fails for any new one.

@AnalyzeClasses(packages = "com.shop")
class ArchitectureTest {
    @ArchTest
    static final ArchRule noCycles = freeze(
        slices().matching("com.shop.(*)..").should().beFreeOfCycles());
}

Result. No new cycles were introduced after the rule was added, and the frozen violations shrank from 14 to 2 over two quarters as teams fixed them during normal work.

Takeaway. Turn architectural rules into executable tests. Freezing existing violations lets you introduce rules into legacy code without stopping delivery, while still preventing things from getting worse.

6.12 Worked example — architecture vs framework

Scenario. In a client presentation, a team described their solution's architecture as "Spring Boot on Kubernetes". The client's architect asked how the system was structured, and the team had no clear answer.

Walkthrough. Naming frameworks and platforms describes technology choices, not architecture. A useful description states structure and behaviour: for example, a modular monolith with modules for orders, payments and catalogue, integrated through in-process events, deployed as one Spring Boot application on Kubernetes. That sentence tells the listener how the system is divided, how parts communicate and how it is deployed.

Result. The team rewrote their architecture summary around structure, communication and deployment, and moved the technology list to a separate section. The client's follow-up questions became about trade-offs rather than buzzwords.

Takeaway. Describe architecture by its structures, interactions and key decisions; mention technologies as supporting choices. Tools change far more often than structure.

6.13 Worked example — runtime behaviour metrics

Scenario. An architecture review claimed that ShopNow's checkout was "fast and resilient". The review board asked how anyone would know if that stopped being true.

Walkthrough. The team defined metrics for each aspect of runtime behaviour. Interaction latency is measured as p99 per call between services. Throughput is measured in orders per second at peak. Failure handling is measured through error rates and retry rates per dependency. Each metric has a target, a dashboard and an alert.

# Example SLOs for checkout behaviour
checkout-latency:   { metric: http.server.requests, uri: /api/checkout, p99: 800ms }
checkout-throughput: { metric: orders.placed, target: 120/s at peak }
payment-retries:    { metric: resilience4j.retry.calls, kind: failed_with_retry, max: 1% }

Result. When a dependency upgrade doubled payment retries a month later, the alert fired before customers noticed, and the team rolled back the change.

Takeaway. Architectural behaviour is measurable. Turn claims such as "fast" and "resilient" into metrics with targets, so the architecture can be verified continuously.

6.14 Worked example — who decides

Scenario. Teams at ShopNow complained that architects slowed them down by reviewing everything, while architects complained that teams made boundary-changing decisions without telling anyone.

Walkthrough. The architecture group published decision rights based on significance. Service and module boundaries, integration styles and data ownership are decided by architects together with tech leads, because they affect many teams. Internal class design, libraries within approved lists and code structure inside a module are decided by the team alone.

Result. Review requests fell by more than half, and the decisions that still reached the architects were the ones that mattered. Teams also knew exactly when to involve an architect.

Takeaway. Make decision rights explicit and tie them to significance. Clear rights speed teams up and protect the decisions that really need wider input.

6.15 Worked example — ISO 42010 terms applied

Scenario. ShopNow's architecture documents used words like "view", "perspective" and "concern" inconsistently, so readers often misunderstood what a section was meant to cover.

Walkthrough. The team adopted ISO/IEC/IEEE 42010 vocabulary. The system is the order platform. Stakeholders are people with interests in it, such as operations. A concern is something a stakeholder cares about, such as recoverability. A view is a representation addressing specific concerns, such as the deployment view showing how the system recovers from a zone failure. Each document section now states which stakeholders and concerns it addresses.

Result. Reviews became more focused: stakeholders could find the views relevant to them, and missing concerns, such as security for the compliance team, were easy to spot.

Takeaway. Use a standard vocabulary for architecture descriptions. Naming stakeholders and concerns explicitly shows which views are needed and which are missing.

6.16 Worked example — architecture description outline

Scenario. A new project's architecture document had reached 80 pages and nobody read it. The team asked what the minimum useful description would be.

Walkthrough. The architect proposed four sections. Drivers capture business goals, quality requirements and constraints. Structures show C4 context, container and component views. Behaviour shows a few key runtime sequences, such as checkout and refund. Decisions are recorded as short ADRs linked from the relevant views. Everything else, such as detailed API specifications, lives in the code repositories.

docs/architecture/
  01-drivers.md        goals, quality attributes, constraints
  02-structures.md     C4 context + container + key components
  03-behaviour.md      checkout and refund sequences
  adr/                 ADR-001 ... ADR-023

Result. The new description fits in about 15 pages plus ADRs, is updated in the same pull requests as code changes, and is actually read by new engineers.

Takeaway. A short, current architecture description is far more valuable than a long, stale one. Cover drivers, structures, behaviour and decisions, and keep it next to the code.

6.17 Worked example — erosion metric

Scenario. ShopNow's leadership asked whether two years of architecture work had actually improved the code base, or just produced documents.

Walkthrough. The architecture group tracked two simple health metrics over time. The number of frozen ArchUnit violations shows legacy rule-breaking being paid down. The number of dependencies between modules shows whether coupling is stable or growing.

Result. Frozen violations fell steadily over six quarters, while cross-module dependencies stayed flat even as features were added. Leadership could see the architecture improving in data rather than opinion.

Takeaway. Track a few architecture health metrics and review them regularly. Trends are more useful than absolute numbers, and they show whether architecture is enforced in practice.

6.18 Worked example — interview answer

Scenario. In interviews for architect roles, ShopNow found that many candidates could define architecture in one sentence but could not explain why the definition mattered.

How to answer. A strong answer has three parts. The definition: architecture is the set of significant structures and decisions of a system. The distinction: it differs from design by its system-wide scope, its link to quality attributes and its high cost of change. The evidence: architecture is made visible through views, recorded in ADRs and protected by fitness functions such as ArchUnit rules.

Why it works. Candidates who answered in this structure, with a short example from their own work, consistently performed better in the deeper design discussion that followed.

Takeaway. In interviews, follow a definition with a distinction and evidence from practice. That shows you understand architecture as a working discipline, not just a term.

7Common Problems & Mistakes

• Equating architecture with technology stack.
• Treating significant decisions as design details.
• Ignoring runtime behaviour in architecture.
• Architecture only in slides, not enforced in code.
• Over-architecting trivial decisions.
• No distinction between intended and implemented architecture.

8Performance & Production Considerations

9Architecture & Design Considerations

• Define architecture by significance and reversibility.
• Describe structure and behaviour together.
• Make architecture executable through fitness functions.
• Let quality attributes drive structure.

10Interview Questions & Answers