Software Architecture Document Template (4+1 Views)

SAD with Kruchten 4+1 views – goals and constraints, scenarios, logical, process, development, physical views, sizing, view mapping

Arquitectura y diseño de sistemasCompletaKruchten 4+1 view model4plus1 mathActualizada 20 oct 2026

Abrir en el editorDescargar .md

Cómo usar: Larger systems where different audiences need different views. Pick five to ten significant scenarios first; they drive and validate the four views. Fill section 10 (mapping between views) – if you cannot, the views describe different systems.

Vista previa

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.

Document control

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

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

Introduction
Architectural goals and constraints
Use-case view (scenarios)
Logical view
Process view
Development view
Physical view
Size and performance
Quality
Mapping between views
Glossary and references

1. Introduction

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

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)

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

4.1 Overview

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

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

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.

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

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

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

7.1 Deployment topology

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

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

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

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

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

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.

Plantillas relacionadas

Arquitectura y diseño de sistemas