# Software Architecture Document: [System name]

> Software architecture document (SAD) organised around Philippe
> Kruchten's "4+1" view model: logical, process, development and physical
> views, tied together and validated by a set of scenarios. Replace every
> `[bracketed]` value and every row marked *Example*.

<!--
Guidance: How to use this template
- Start with section 2 (goals and constraints) and section 3 (scenarios).
  The scenarios are the "+1": they select what the four views must show and
  are later used to walk through the views and check they agree.
- Write each view for its main audience: logical for analysts and
  designers, process for integrators and performance engineers,
  development for programmers and managers, physical for operations.
- Section 9 maps elements between views. If you cannot fill it, the views
  are describing different systems.
-->

## Document control

<!-- Guidance: Identify the SAD and the release it describes. -->

| Field | Value |
|---|---|
| Document ID | [SAD-SYSTEM-001] |
| System | [System name] |
| Release described | [vX.Y] |
| Version | [0.1] |
| Status | [Draft / In review / Approved] |
| Architect / owner | [@architect] |
| Classification | [Internal / Confidential / Public] |
| Last updated | YYYY-MM-DD |

### Approvals

| Role | Name | Decision | Date |
|---|---|---|---|
| Chief architect | [@name] | [Approved / Approved with comments / Rejected] | YYYY-MM-DD |
| Development manager | [@name] | [Decision] | YYYY-MM-DD |
| Test manager | [@name] | [Decision] | YYYY-MM-DD |
| Operations manager | [@name] | [Decision] | YYYY-MM-DD |

## Revision history

<!-- Guidance: Note which view or scenario changed in each entry. -->

| Version | Date | Author | Change summary |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | [@name] | Goals, constraints and scenarios |
| 0.2 | YYYY-MM-DD | [@name] | *Example:* Process view with concurrency model; physical view for two data centres |
| 1.0 | YYYY-MM-DD | [@name] | *Example:* Baseline after scenario walkthrough |

## Contents

1. [Introduction](#1-introduction)
2. [Architectural goals and constraints](#2-architectural-goals-and-constraints)
3. [Use-case view (scenarios)](#3-use-case-view-scenarios)
4. [Logical view](#4-logical-view)
5. [Process view](#5-process-view)
6. [Development view](#6-development-view)
7. [Physical view](#7-physical-view)
8. [Size and performance](#8-size-and-performance)
9. [Quality](#9-quality)
10. [Mapping between views](#10-mapping-between-views)
11. [Glossary and references](#11-glossary-and-references)

## 1. Introduction

<!-- Guidance: State the purpose, scope and audience of the SAD and how the five views are used. -->

### 1.1 Purpose

This document gives a comprehensive overview of the architecture of
[System name], using several views to describe different aspects. It
records the significant architectural decisions and is the reference for
[design, implementation, test planning and operations].

### 1.2 Scope

[What the document covers: the system, its release, and what is left to
other documents such as detailed designs or interface specifications.]

### 1.3 Views and their audiences

| View | Main concern | Primary readers | Section |
|---|---|---|---|
| Use-case (scenarios) | Architecturally significant behaviour | All | 3 |
| Logical | Functional decomposition, key abstractions | Analysts, designers | 4 |
| Process | Concurrency, distribution, performance, availability | Integrators, performance engineers | 5 |
| Development | Software organisation, reuse, build | Developers, managers | 6 |
| Physical | Mapping to hardware, topology, deployment | Operations, system engineers | 7 |

## 2. Architectural goals and constraints

<!-- Guidance: List the requirements and constraints that have significant impact on the architecture. Each should influence at least one view; if it influences nothing, it is not architectural. -->

### 2.1 Goals

| ID | Goal | Measure | Views most affected |
|---|---|---|---|
| AG-01 | *Example:* Process 500 claims per minute at peak | Throughput test | Process, physical |
| AG-02 | *Example:* Remain available during a single data centre outage | 99.95% monthly | Physical, process |
| AG-03 | *Example:* Allow three teams to release independently | Release frequency per team | Development, logical |
| [AG-nn] | [Goal] | [Measure] | [Views] |

### 2.2 Constraints

| ID | Constraint | Source | Views affected |
|---|---|---|---|
| AC-01 | *Example:* Must use the corporate Oracle database | IT standards | Physical, logical |
| AC-02 | *Example:* Personal data stays in the EU | GDPR | Physical |
| AC-03 | *Example:* Java 21 and the corporate CI toolchain | Engineering policy | Development |
| [AC-nn] | [Constraint] | [Source] | [Views] |

### 2.3 Significant architectural decisions

The decisions below shape more than one view. Each is recorded in full in
the decision log (REF-02); this table keeps the reasoning visible to
readers of the SAD.

| ID | Decision | Alternatives rejected | Goals / constraints served | Views |
|---|---|---|---|---|
| AD-001 | *Example:* Event-driven integration between claims and fraud scoring | Synchronous REST call from claims to fraud | AG-01 (throughput), AG-03 (independent releases) | Logical, process, development |
| AD-002 | *Example:* Active-passive data centres with synchronous database replication | Active-active with conflict resolution | AG-02 (availability), AC-01 (Oracle) | Physical, process |
| AD-003 | *Example:* Layered modules with architecture tests in the build | Convention only | AG-03 (maintainability) | Development |
| [AD-nnn] | [Decision] | [Alternatives] | [IDs] | [Views] |

## 3. Use-case view (scenarios)

<!-- Guidance: Select the scenarios that exercise the architecture most: central functions, risky paths, quality-critical flows. Typically five to ten. They drive and validate the other four views. -->

### 3.1 Architecturally significant use cases

| ID | Scenario | Actor | Why significant | Exercises views |
|---|---|---|---|---|
| UC-01 | *Example:* Submit insurance claim with documents | Policyholder | Highest volume, touches every subsystem | All |
| UC-02 | *Example:* Automated fraud check | System | CPU-heavy, latency-sensitive | Process, physical |
| UC-03 | *Example:* Adjuster approves payout | Claims adjuster | Integrates with payment system | Logical, process |
| UC-04 | *Example:* Fail over to second data centre | Operations | Availability goal AG-02 | Physical, process |
| [UC-nn] | [Scenario] | [Actor] | [Reason] | [Views] |

### 3.2 Use-case realisation summary

[For each scenario, a few lines on how the architecture handles it, with a
reference to the sequence diagram in section 5 or the table in section 10.
Example: "UC-01: the portal uploads documents to object storage, the
claims service creates the claim and publishes ClaimSubmitted; fraud and
document services react asynchronously."]

## 4. Logical view

<!-- Guidance: The object model of the design: main packages or subsystems and the key classes in each. Focus on the abstractions that carry the significant scenarios. -->

### 4.1 Overview

The system is decomposed into [three] layers and [five] subsystems. The
key abstractions of the claims domain are shown below.

```mermaid
classDiagram
  class Claim {
    +ClaimId id
    +ClaimStatus status
    +Money requestedAmount
    +submit()
    +approve(adjuster)
  }
  class Policy {
    +PolicyNumber number
    +Coverage coverage
    +isActiveOn(date) bool
  }
  class Document {
    +DocumentId id
    +String mediaType
  }
  class FraudAssessment {
    +Score score
    +List~Reason~ reasons
  }
  Claim "*" --> "1" Policy : made under
  Claim "1" *-- "*" Document : supported by
  Claim "1" --> "0..1" FraudAssessment : assessed by
```

### 4.2 Architecturally significant packages

| Package / subsystem | Responsibility | Key classes | Depends on |
|---|---|---|---|
| *Example:* Claims | Claim lifecycle and rules | `Claim`, `ClaimService` | Policies, Documents |
| *Example:* Policies | Policy lookup and coverage rules | `Policy`, `Coverage` | None |
| *Example:* Fraud | Scoring and explanations | `FraudAssessment`, `RuleEngine` | Claims (events only) |
| [Package] | [Responsibility] | [Classes] | [Dependencies] |

## 5. Process view

<!-- Guidance: Describe the runtime: processes and threads, how they communicate, concurrency and synchronisation, and how the process structure meets performance and availability goals. -->

### 5.1 Processes and threads

| Process | Instances | Threads / concurrency model | Communication | Started by |
|---|---|---|---|---|
| *Example:* Portal web server | 4 | Event loop, non-blocking I/O | HTTPS to API gateway | Orchestrator |
| *Example:* Claims service | 3 | Thread pool of 200 request threads | REST in, events out | Orchestrator |
| *Example:* Fraud scorer | 2 to 8 | One consumer thread per partition | Consumes `claims.submitted` | Autoscaler |
| [Process] | [n] | [Model] | [Mechanism] | [Start] |

### 5.2 Interaction for UC-01 submit claim

The sequence below shows the processes involved when a policyholder
submits a claim.

```mermaid
sequenceDiagram
  actor P as Policyholder
  participant Portal
  participant Claims as Claims service
  participant Bus as Event bus
  participant Fraud as Fraud scorer
  P->>Portal: Submit claim and documents
  Portal->>Claims: POST /claims
  Claims->>Claims: Validate against policy
  Claims->>Bus: ClaimSubmitted
  Claims-->>Portal: 202 Accepted, claim ID
  Portal-->>P: Confirmation
  Bus->>Fraud: ClaimSubmitted
  Fraud->>Bus: FraudAssessed(score)
  Bus->>Claims: FraudAssessed(score)
```

### 5.3 Concurrency and synchronisation

[Shared resources and how access is controlled: optimistic locking on
claims (version column), idempotent event handlers keyed by event ID,
partitioning by claim ID so events for one claim are processed in order.]

### 5.4 Failure and recovery behaviour

Each process has a defined behaviour when it, or something it depends on,
fails. Operations uses this table to design alerts and runbooks.

| Failure | Detected by | Process behaviour | Recovery | Data at risk |
|---|---|---|---|---|
| *Example:* Fraud scorer down | Consumer lag alert above 5 minutes | Claims accepted; assessment delayed; adjusters see "pending score" | Autoscaler restarts pods; backlog drains | None (events retained 7 days) |
| *Example:* Event bus unavailable | Publish errors in claims service | Claims service writes events to outbox table and retries | Outbox relay resumes on recovery | None |
| *Example:* Database primary lost | Health check, replication monitor | Writes fail fast with 503; portal shows maintenance notice | Promote standby in data centre B (UC-04) | Zero with synchronous replication |
| [Failure] | [Signal] | [Behaviour] | [Recovery] | [Data] |

## 6. Development view

<!-- Guidance: How the software is organised in the development environment: layers, modules, repositories, ownership, build and reuse rules. -->

### 6.1 Layers

| Layer | Contents | May depend on |
|---|---|---|
| Presentation | Web portal, adjuster UI | Application |
| Application | Use-case services, API controllers | Domain, infrastructure interfaces |
| Domain | Entities, value objects, domain rules | Nothing outside the domain |
| Infrastructure | Database, messaging, external clients | Domain interfaces |

### 6.2 Modules and ownership

```mermaid
flowchart TB
  portal[portal-web] --> api[claims-api]
  api --> domain[claims-domain]
  api --> infra[claims-infra]
  infra --> domain
  fraud[fraud-scorer] --> events[shared-events]
  api --> events
```

| Module / repository | Owner team | Build artefact | Release cadence |
|---|---|---|---|
| *Example:* claims-api | Team Claims | Container image | Weekly |
| *Example:* fraud-scorer | Team Risk | Container image | On demand |
| *Example:* shared-events | Platform | Library (semantic versioning) | When schemas change |
| [Module] | [Team] | [Artefact] | [Cadence] |

### 6.3 Development rules

[Build tools, dependency rules enforced by architecture tests, code
generation, shared libraries, and the policy for changing shared event
schemas (for example "additive changes only within a major version").]

## 7. Physical view

<!-- Guidance: Map processes to nodes, show network topology and how the physical configuration meets availability, performance and data residency constraints. -->

### 7.1 Deployment topology

The system runs in two data centres in active-passive configuration.

```mermaid
flowchart LR
  subgraph dc1 [Data centre A, active]
    lb1[Load balancer] --> app1[App nodes x3]
    app1 --> db1[(Oracle primary)]
    app1 --> bus1[[Event bus cluster]]
  end
  subgraph dc2 [Data centre B, standby]
    lb2[Load balancer] --> app2[App nodes x3]
    app2 --> db2[(Oracle standby)]
  end
  db1 -. synchronous replication .-> db2
  users([Users]) --> dns[Global DNS] --> lb1
  dns -.-> lb2
```

### 7.2 Nodes

| Node | Specification | Processes hosted | Count |
|---|---|---|---|
| *Example:* App node | 8 vCPU, 32 GB RAM | Portal, claims service, fraud scorer | 3 per data centre |
| *Example:* Database server | 32 vCPU, 256 GB RAM, SAN | Oracle | 1 per data centre |
| [Node] | [Spec] | [Processes] | [n] |

### 7.3 Environments

| Environment | Purpose | Topology | Data | Refresh |
|---|---|---|---|---|
| *Example:* Production | Live service | Two data centres as in 7.1 | Real customer data | n/a |
| *Example:* Pre-production | Release and failover rehearsal | Two small data centres, same topology | Masked copy of production | Monthly |
| *Example:* Test | Integration and performance tests | Single site | Synthetic | Per test run |
| [Environment] | [Purpose] | [Topology] | [Data] | [Refresh] |

## 8. Size and performance

<!-- Guidance: Give the dimensioning characteristics and performance targets that constrain the architecture, with the calculation behind them. -->

Peak claim submission load is derived from annual volume and seasonal
peaks:

$$
\lambda_{peak} = \frac{V_{year}}{365 \times 8\,\text{h} \times 3600} \times k_{peak} = \frac{2\,400\,000}{10\,512\,000} \times 25 \approx 5.7\ \text{claims/s}
$$

| Characteristic | Target | Basis |
|---|---|---|
| *Example:* Claims per year | 2.4 million | Business forecast YYYY |
| *Example:* Peak submissions | 6 per second (storm events) | Formula above, peak factor 25 |
| *Example:* Claim submission latency | p95 under 2 s | AG-01 |
| *Example:* Document storage growth | 15 TB per year | 6 MB average per claim |
| [Characteristic] | [Target] | [Basis] |

## 9. Quality

<!-- Guidance: Explain how the architecture contributes to quality attributes other than performance: availability, security, maintainability, portability. -->

| Quality attribute | Target | Architectural contribution | Views |
|---|---|---|---|
| *Example:* Availability | 99.95% monthly | Active-passive data centres, stateless app nodes, synchronous database replication | Physical, process |
| *Example:* Security | Personal data encrypted at rest and in transit | TLS everywhere, transparent database encryption, role-based access in claims service | Physical, logical |
| *Example:* Maintainability | Teams release independently | Separate modules and images, event contracts versioned | Development |
| [Attribute] | [Target] | [Contribution] | [Views] |

## 10. Mapping between views

<!-- Guidance: Show how elements in one view correspond to elements in the others, and walk the significant scenarios through all views. This is the consistency check of the 4+1 model. -->

### 10.1 Element mapping

| Logical element | Process | Development module | Physical node |
|---|---|---|---|
| *Example:* Claims package | Claims service | claims-api, claims-domain, claims-infra | App nodes |
| *Example:* Fraud package | Fraud scorer | fraud-scorer | App nodes |
| *Example:* Claim, Policy entities | Claims service (owner) | claims-domain | Oracle database |
| [Element] | [Process] | [Module] | [Node] |

### 10.2 Scenario walkthrough results

| Scenario | Walkthrough date | Views consistent | Issues found | Action |
|---|---|---|---|---|
| *Example:* UC-01 | YYYY-MM-DD | Yes | None | None |
| *Example:* UC-04 | YYYY-MM-DD | No | Event bus has no standby in data centre B | AD-007 opened |
| [UC-nn] | YYYY-MM-DD | [Yes / No] | [Issues] | [Action] |

## 11. Glossary and references

<!-- Guidance: Define terms and list the documents this SAD relies on. -->

### 11.1 Glossary

| Term | Meaning |
|---|---|
| View | A description of the system from one perspective, for one set of concerns |
| Scenario | A sequence of interactions used to drive and validate the architecture |
| Process | A group of tasks forming an executable unit, possibly distributed |
| [Term] | [Meaning] |

### 11.2 References

| ID | Document | Version |
|---|---|---|
| REF-01 | [Requirements specification] | [x.y] |
| REF-02 | [Architecture decision log] | [Location] |
| REF-03 | Kruchten, P., "Architectural Blueprints: The 4+1 View Model of Software Architecture", IEEE Software 12(6), 1995 | 1995 |

## Standard and licence note

Based on the "4+1" view model of software architecture described by
Philippe Kruchten (IEEE Software, 1995): logical, process, development and
physical views, plus scenarios that tie them together. This template is
original text written for this collection and reproduces no text from the
paper. Template licence: MIT.